computeCumulativeDistance

COMPUTECUMULATIVEDISTANCE  Cumulate distance along given trajectory.

  Syntax:
    DISTANCE = COMPUTECUMULATIVEDISTANCE(LATITUDE, LONGITUDE)

  Description:
    DISTANCE = COMPUTECUMULATIVEDISTANCE(LATITUDE, LONGITUDE) computes the
    cumulative distance (in km) of a trajectory defined by coordinate vectors 
    LATITUDE and LONGITUDE. DISTANCE, LATITUDE and LONGITUDE have the same 
    dimensions. Invalid values (NaN) are ignored but preserved in output.

  Notes:
    Two functions may be used to compute distance between consecutive 
    geographical coordinates: 
      M_LLDIST (from M_Map toolbox)
      SW_DIST (from CSIRO's SeaWater library)
    Function M_LLDIST is preferred because its method (haversine) seems to be
    more accurate. If it is not available, function SW_DIST is used instead.
    
  Examples:
    latitude  = [39.50   nan 39.50  nan 39.21   nan 39.23   nan   nan   nan 38.98   nan 38.98]
    longitude = [ 2.18   nan   nan  nan  1.65   nan  1.28   nan  1.09   nan  1.09   nan  0.12]
    distance = computeCumulativeDistance(latitude, longitude)

  See also:
    M_LLDIST
    SW_DIST

  Authors:
    Joan Pau Beltran  <joanpau.beltran@socib.cat>

0001 function distance = computeCumulativeDistance(latitude, longitude)
0002 %COMPUTECUMULATIVEDISTANCE  Cumulate distance along given trajectory.
0003 %
0004 %  Syntax:
0005 %    DISTANCE = COMPUTECUMULATIVEDISTANCE(LATITUDE, LONGITUDE)
0006 %
0007 %  Description:
0008 %    DISTANCE = COMPUTECUMULATIVEDISTANCE(LATITUDE, LONGITUDE) computes the
0009 %    cumulative distance (in km) of a trajectory defined by coordinate vectors
0010 %    LATITUDE and LONGITUDE. DISTANCE, LATITUDE and LONGITUDE have the same
0011 %    dimensions. Invalid values (NaN) are ignored but preserved in output.
0012 %
0013 %  Notes:
0014 %    Two functions may be used to compute distance between consecutive
0015 %    geographical coordinates:
0016 %      M_LLDIST (from M_Map toolbox)
0017 %      SW_DIST (from CSIRO's SeaWater library)
0018 %    Function M_LLDIST is preferred because its method (haversine) seems to be
0019 %    more accurate. If it is not available, function SW_DIST is used instead.
0020 %
0021 %  Examples:
0022 %    latitude  = [39.50   nan 39.50  nan 39.21   nan 39.23   nan   nan   nan 38.98   nan 38.98]
0023 %    longitude = [ 2.18   nan   nan  nan  1.65   nan  1.28   nan  1.09   nan  1.09   nan  0.12]
0024 %    distance = computeCumulativeDistance(latitude, longitude)
0025 %
0026 %  See also:
0027 %    M_LLDIST
0028 %    SW_DIST
0029 %
0030 %  Authors:
0031 %    Joan Pau Beltran  <joanpau.beltran@socib.cat>
0032 
0033 %  Copyright (C) 2013-2016
0034 %  ICTS SOCIB - Servei d'observacio i prediccio costaner de les Illes Balears
0035 %  <http://www.socib.es>
0036 %
0037 %  This program is free software: you can redistribute it and/or modify
0038 %  it under the terms of the GNU General Public License as published by
0039 %  the Free Software Foundation, either version 3 of the License, or
0040 %  (at your option) any later version.
0041 %
0042 %  This program is distributed in the hope that it will be useful,
0043 %  but WITHOUT ANY WARRANTY; without even the implied warranty of
0044 %  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
0045 %  GNU General Public License for more details.
0046 %
0047 %  You should have received a copy of the GNU General Public License
0048 %  along with this program.  If not, see <http://www.gnu.org/licenses/>.
0049 
0050   error(nargchk(2, 2, nargin, 'struct'));
0051   
0052   distance = nan(size(latitude));
0053   valid_point_sel = ~(isnan(latitude) | isnan(longitude));
0054   latitude_valid = latitude(valid_point_sel);
0055   longitude_valid = longitude(valid_point_sel);
0056   switch sum(valid_point_sel)
0057     case 0
0058     case 1
0059       distance(valid_point_sel) = 0;
0060     otherwise
0061       if exist('m_lldist', 'file') == 2 % exists and is a file (not a folder)
0062         distance(valid_point_sel) = ...
0063           cumsum([0; m_lldist(longitude_valid(:), latitude_valid(:))]);
0064       elseif exist('sw_dist', 'file') == 2
0065         distance(valid_point_sel) = ...
0066           cumsum([0; sw_dist(latitude_valid(:), longitude_valid(:), 'km')]);
0067       else
0068         error('glider_toolbox:computeCumulativeDistance:MissingBackendFunction', ...
0069               'Missing backend functions: m_lldist (preferred) or sw_dist');
0070       end
0071   end
0072 
0073 end