Flight Path & INS Data

The following are key functions related to obtaining flight path & INS data.

Load Flight Data

MagNav.get_XYZ0 — Function

get_XYZ0(xyz_file::String,
         traj_field::Symbol = :traj,
         ins_field::Symbol  = :ins_data;
         flight             = 1,
         line               = 1,
         dt                 = 0.1,
         silent::Bool       = false)

Get the minimum dataset required for MagNav from saved HDF5 or MAT file. Not all fields within the XYZ0 flight data struct are required. The minimum data required in the HDF5 or MAT file includes:

lat, lon, alt (position)
mag_1_uc OR mag_1_c (scalar magnetometer measurements)

If an HDF5 file is provided, the possible fields in the file are:

Field	Type	Description
`dt`	scalar	measurement time step [s]
`tt`	vector	time [s]
`lat`	vector	latitude [deg]
`lon`	vector	longitude [deg]
`alt`	vector	altitude [m]
`vn`	vector	north velocity [m/s]
`ve`	vector	east velocity [m/s]
`vd`	vector	down velocity [m/s]
`fn`	vector	north specific force [m/s]
`fe`	vector	east specific force [m/s]
`fd`	vector	down specific force [m/s]
`Cnb`	3x3xN	direction cosine matrix (body to navigation) [-]
`roll`	vector	roll [deg]
`pitch`	vector	pitch [deg]
`yaw`	vector	yaw [deg]
`ins_dt`	scalar	INS measurement time step [s]
`ins_tt`	vector	INS time [s]
`ins_lat`	vector	INS latitude [deg]
`ins_lon`	vector	INS longitude [deg]
`ins_alt`	vector	INS altitude [m]
`ins_vn`	vector	INS north velocity [m/s]
`ins_ve`	vector	INS east velocity [m/s]
`ins_vd`	vector	INS down velocity [m/s]
`ins_fn`	vector	INS north specific force [m/s]
`ins_fe`	vector	INS east specific force [m/s]
`ins_fd`	vector	INS down specific force [m/s]
`ins_Cnb`	3x3xN	INS direction cosine matrix (body to navigation) [-]
`ins_roll`	vector	INS roll [deg]
`ins_pitch`	vector	INS pitch [deg]
`ins_yaw`	vector	INS yaw [deg]
`ins_P`	17x17xN	INS covariance matrix, only relevant for simulated data, otherwise zeros [-]
`flux_a_x`	vector	Flux A x-direction magnetic field [nT]
`flux_a_y`	vector	Flux A y-direction magnetic field [nT]
`flux_a_z`	vector	Flux A z-direction magnetic field [nT]
`flux_a_t`	vector	Flux A total magnetic field [nT]
`flight`	vector	flight number(s)
`line`	vector	line number(s), i.e., segments within `flight`
`mag_1_c`	vector	Mag 1 compensated (clean) scalar magnetometer measurements [nT]
`mag_1_uc`	vector	Mag 1 uncompensated (corrupted) scalar magnetometer measurements [nT]

If a MAT file is provided, the above fields may also be provided, but the non-INS fields should be within the specified traj_field MAT struct and the INS fields should be within the specified ins_field MAT struct and without ins_ prefixes. This is the standard way the MATLAB-companion outputs data.

Arguments:

xyz_file: path/name of flight data HDF5 or MAT file (.h5 or .mat extension required)
traj_field: (optional) trajectory struct field within MAT file to use, not relevant for HDF5 file
ins_field: (optional) INS struct field within MAT file to use, :none if unavailable, not relevant for HDF5 file
flight: (optional) flight number, only used if not in xyz_file
line: (optional) line number, i.e., segment within flight, only used if not in xyz_file
dt: (optional) measurement time step [s], only used if not in xyz_file
silent: (optional) if true, no print outs

Returns:

xyz: XYZ0 flight data struct

MagNav.get_XYZ20 — Function

get_XYZ20(xyz_h5::String; tt_sort::Bool=true, silent::Bool=false)

Get XYZ20 flight data from saved HDF5 file. Based on SGL 2020 data fields.

Arguments:

xyz_h5: path/name of flight data HDF5 file (.h5 extension optional)
tt_sort: (optional) if true, sort data by time (instead of line)
silent: (optional) if true, no print outs

Returns:

xyz: XYZ20 flight data struct

get_XYZ20(xyz_160_h5::String, xyz_h5::String; silent::Bool=false)

Get 160 Hz (partial) XYZ20 flight data from saved HDF5 file and combine with 10 Hz XYZ20 flight data from another saved HDF5 file. Data is time sorted to ensure data is aligned.

Arguments:

xyz_160_h5: path/name of 160 Hz flight data HDF5 file (.h5 extension optional)
xyz_h5: path/name of 10 Hz flight data HDF5 file (.h5 extension optional)
silent: (optional) if true, no print outs

Returns:

xyz: XYZ20 flight data struct

MagNav.get_XYZ — Function

get_XYZ(flight::Symbol, df_flight::DataFrame; tt_sort::Bool=true,
        reorient_vec::Bool=false, silent::Bool=false)

Get XYZ flight data from saved HDF5 file via DataFrame lookup.

Arguments:

flight: flight name (e.g., :Flt1001)
df_flight: lookup table (DataFrame) of flight data HDF5 files

Field	Type	Description
`flight`	`Symbol`	flight name (e.g., `:Flt1001`)
`xyz_type`	`Symbol`	subtype of `XYZ` to use for flight data {`:XYZ0`,`:XYZ1`,`:XYZ20`,`:XYZ21`}
`xyz_set`	`Real`	flight dataset number (used to prevent inproper mixing of datasets, such as different magnetometer locations)
`xyz_h5`	`String`	path/name of flight data HDF5 file (`.h5` extension optional)

tt_sort: (optional) if true, sort data by time (instead of line)
reorient_vec: (optional) if true, align vector magnetometer measurements with body frame
silent: (optional) if true, no print outs

Returns:

xyz: XYZ flight data struct

Create Flight Data

MagNav.create_XYZ0 — Function

create_XYZ0(mapS::Union{MapS,MapSd,MapS3D} = get_map(namad);
            alt            = 1000,
            dt             = 0.1,
            t              = 300,
            v              = 68,
            ll1            = (),
            ll2            = (),
            N_waves        = 1,
            flight         = 1,
            line           = 1,
            attempts::Int  = 10,
            mapV::MapV     = get_map(emm720),
            cor_sigma      = 1.0,
            cor_tau        = 600.0,
            cor_var        = 1.0^2,
            cor_drift      = 0.001,
            cor_perm_mag   = 5.0,
            cor_ind_mag    = 5.0,
            cor_eddy_mag   = 0.5,
            init_pos_sigma = 3.0,
            init_alt_sigma = 0.001,
            init_vel_sigma = 0.01,
            init_att_sigma = deg2rad(0.01),
            VRW_sigma      = 0.000238,
            ARW_sigma      = 0.000000581,
            baro_sigma     = 1.0,
            ha_sigma       = 0.001,
            a_hat_sigma    = 0.01,
            acc_sigma      = 0.000245,
            gyro_sigma     = 0.00000000727,
            fogm_sigma     = 1.0,
            baro_tau       = 3600.0,
            acc_tau        = 3600.0,
            gyro_tau       = 3600.0,
            fogm_tau       = 600.0,
            save_h5::Bool  = false,
            xyz_h5::String = "xyz_data.h5",
            silent::Bool   = false)

Create basic flight data. Assumes constant altitude (2D flight). May create a trajectory that passes over map areas that are missing map data. No required arguments, though many are available to create custom data.

Trajectory Arguments:

mapS: (optional) MapS, MapSd, or MapS3D scalar magnetic anomaly map struct
alt: (optional) altitude [m]
dt: (optional) measurement time step [s]
t: (optional) total flight time, ignored if ll2 is set [s]
v: (optional) approximate aircraft velocity [m/s]
ll1: (optional) inital (lat,lon) point [deg]
ll2: (optional) final (lat,lon) point [deg]
N_waves: (optional) number of sine waves along path
mapV: (optional) MapV vector magnetic anomaly map struct
flight: (optional) flight number
line: (optional) line number, i.e., segment within flight
attempts: (optional) maximum attempts at creating flight path on mapS
save_h5: (optional) if true, save xyz to xyz_h5
xyz_h5: (optional) path/name of flight data HDF5 file to save (.h5 extension optional)

Compensated Measurement Corruption Arguments:

cor_var: (optional) corruption measurement (white) noise variance [nT^2]
fogm_sigma: (optional) FOGM catch-all bias [nT]
fogm_tau: (optional) FOGM catch-all time constant [s]

Uncompensated Measurement Corruption Arguments:

cor_sigma: (optional) corruption FOGM catch-all bias [nT]
cor_tau: (optional) corruption FOGM catch-all time constant [s]
cor_var: (optional) corruption measurement (white) noise variance [nT^2]
cor_drift: (optional) corruption measurement linear drift [nT/s]
cor_perm_mag: (optional) corruption permanent field TL coef std dev
cor_ind_mag: (optional) corruption induced field TL coef std dev
cor_eddy_mag: (optional) corruption eddy current TL coef std dev

INS Arguments:

init_pos_sigma: (optional) initial position uncertainty [m]
init_alt_sigma: (optional) initial altitude uncertainty [m]
init_vel_sigma: (optional) initial velocity uncertainty [m/s]
init_att_sigma: (optional) initial attitude uncertainty [rad]
VRW_sigma: (optional) velocity random walk [m/s^2 /sqrt(Hz)]
ARW_sigma: (optional) angular random walk [rad/s /sqrt(Hz)]
baro_sigma: (optional) barometer bias [m]
ha_sigma: (optional) barometer aiding altitude bias [m]
a_hat_sigma: (optional) barometer aiding vertical accel bias [m/s^2]
acc_sigma: (optional) accelerometer bias [m/s^2]
gyro_sigma: (optional) gyroscope bias [rad/s]
baro_tau: (optional) barometer time constant [s]
acc_tau: (optional) accelerometer time constant [s]
gyro_tau: (optional) gyroscope time constant [s]

General Arguments:

silent: (optional) if true, no print outs

Returns:

xyz: XYZ0 flight data struct