Home > . > read_civxdata.m

# read_civxdata

## PURPOSE

'read_civxdata': reads civx data from netcdf files

## SYNOPSIS

function [Field,VelTypeOut]=read_civxdata(filename,FieldNames,VelType)

## DESCRIPTION

    'read_civxdata': reads civx data from netcdf files
    ------------------------------------------------------------------
     COMBINE ET REMPLACE read_ncfield, read_vel et read_scalar_new
    ------------------------------------------------------------------
     OUTPUT:
     nb_coord,nb_dim,
     Civ: =0 or 1, indicates whether the data is civ (A SUPPRIMER ?)
     CivStage: =0, ??? A UTILISER POUR REMPLACER civ
               =1, civ1 has been performed only
               =2, fix1 has been performed
               =3, pacth1 has been performed
               =4, civ2 has been performed
               =5, fix2 has been performed
               =6, pacth2 has been performed
     time: absolute time
     Field
                .Txt: (char string) error message if any
                .NbDim: number of dimensions (=0 by default)
                .NbCoord: number of vector components
                .CoordType: expresses the type of coordinate ('px' for image, 'sig' for instruments, or 'phys')
                .dt: time interval for the corresponding image pair
                .CivStage: =0, ??? A UTILISER POUR REMPLACER civ
               =1, civ1 has been performed only
               =2, fix1 has been performed
               =3, pacth1 has been performed
               =4, civ2 has been performed
               =5, fix2 has been performed
               =6, pacth2 has been performed
                .X, .Y, .Z: set of vector coordinates
                .U,.V,.W: corresponding set of vector components
                .F: warning flags
                .FF: false flag, =0 for good vectors
                .C: scalar associated with velocity (used for vector colors)
                .CoordType
                .DijU; matrix of spatial derivatives (DijU(1,1,:)=DUDX,
                DijU(1,2,:)=DUDY, Dij(2,1,:)=DVDX, DijU(2,2,:)=DVDY
                .A, .AX, .AY: additional scalar
     dt:time interval of the image pair red from a single file, or vector with

## CROSS-REFERENCE INFORMATION

This function calls:

- nc2struct 'nc2struct': transform a netcdf file in a corresponding matlab structure

This function is called by:

- RUN_FIX 'RUN_FIX': function for fixing velocity fields:
- RUN_STLIN 'RUN_STLIN': combine velocity fields for stereo PIV
- series 'series': master function associated to the GUI series.m for analysis field series
- uvmat 'uvmat': function associated with the GUI 'uvmat.fig' for images and data field visualization

## SUBFUNCTIONS

- function [var,role,units,vel_type_out]=varcivx_generator(FieldNames,vel_type)
- function varin=varname1(vel_type,FieldNames)

## SOURCE CODE

    0001 %'read_civxdata': reads civx data from netcdf files
    0002 %------------------------------------------------------------------
    0003 % COMBINE ET REMPLACE read_ncfield, read_vel et read_scalar_new
    0004 %------------------------------------------------------------------
    0005 % OUTPUT:
    0006 % nb_coord,nb_dim,
    0007 % Civ: =0 or 1, indicates whether the data is civ (A SUPPRIMER ?)
    0008 % CivStage: =0, ??? A UTILISER POUR REMPLACER civ
    0009 %           =1, civ1 has been performed only
    0010 %           =2, fix1 has been performed
    0011 %           =3, pacth1 has been performed
    0012 %           =4, civ2 has been performed
    0013 %           =5, fix2 has been performed
    0014 %           =6, pacth2 has been performed
    0015 % time: absolute time
    0016 % Field
    0017 %            .Txt: (char string) error message if any
    0018 %            .NbDim: number of dimensions (=0 by default)
    0019 %            .NbCoord: number of vector components
    0020 %            .CoordType: expresses the type of coordinate ('px' for image, 'sig' for instruments, or 'phys')
    0021 %            .dt: time interval for the corresponding image pair
    0022 %            .CivStage: =0, ??? A UTILISER POUR REMPLACER civ
    0023         %           =1, civ1 has been performed only
    0024         %           =2, fix1 has been performed
    0025         %           =3, pacth1 has been performed
    0026         %           =4, civ2 has been performed
    0027         %           =5, fix2 has been performed
    0028         %           =6, pacth2 has been performed
    0029 %            .X, .Y, .Z: set of vector coordinates
    0030 %            .U,.V,.W: corresponding set of vector components
    0031 %            .F: warning flags
    0032 %            .FF: false flag, =0 for good vectors
    0033 %            .C: scalar associated with velocity (used for vector colors)
    0034 %            .CoordType
    0035 %            .DijU; matrix of spatial derivatives (DijU(1,1,:)=DUDX,
    0036 %            DijU(1,2,:)=DUDY, Dij(2,1,:)=DVDX, DijU(2,2,:)=DVDY
    0037 %            .A, .AX, .AY: additional scalar
    0038 % dt:time interval of the image pair red from a single file, or vector with
    0039
    0040 % pixcmx,pixcmy: scaling factors (from the first file)
    0041 % vel_type_out: string representing the selected velocity type (civ1,civ2,filter1...)
    0042 %
    0043 % INPUT:
    0044 % filename: file name (string).
    0045 % FieldNames =cell of field names to get, which can contain the strings:
    0046 %             'ima_cor': image correlation, vec_c or vec2_C
    0047 %             'vort','div','strain': requires velocity derivatives DUDX...
    0048 %             'error': error estimate (vec_E or vec2_E)
    0049 %
    0050 % VelType : character string indicating the types of velocity fields to read ('civ1','civ2'...)
    0051 %            if vel_type=[] or'*', a  priority choice, given by vel_type_out{1,2}, is done depending
    0052 %            if vel_type='filter'; a structured field is sought (filter2 in priority, then filter1)
    0053
    0054
    0055 % FUNCTIONS called:
    0056 % 'varcivx_generator':, sets the names of vaiables to read in the netcdf file
    0057 % 'nc2struct': reads a netcdf file
    0058
    0059 function [Field,VelTypeOut]=read_civxdata(filename,FieldNames,VelType)
    0060
    0061 if ~exist('VelType','var')
    0062     VelType=[];
    0063 end
    0064 if isequal(VelType,'*')
    0065     VelType=[];
    0066 end
    0067 if ~exist('FieldNames','var')
    0068     FieldNames=[]; %default
    0069 end
    0070
    0071 VelTypeOut=VelType;%default
    0072 [var,role,units,vel_type_out_cell]=varcivx_generator(FieldNames,VelType);%determine the names of constants and variables to read
    0073 [Field,vardetect,ichoice]=nc2struct(filename,var);
    0074 if isfield(Field,'Txt')
    0075     return % error in file reading
    0076 end
    0077 if isequal(vardetect,0)
    0078      Field.Txt=[FieldNames ' not accessible in ' filename '/' VelType];
    0079      return
    0080 end
    0081 var_ind=find(vardetect);
    0082 for ivar=1:length(var_ind)
    0083     Field.VarAttribute{ivar}.Role=role{var_ind(ivar)};
    0084 %     Field.VarAttribute{ivar}.units=units{var_ind(ivar)};% not necessary: set with calc_field
    0085 end
    0086 VelTypeOut=VelType;
    0087 if ~isempty(ichoice)
    0088     VelTypeOut=vel_type_out_cell{ichoice};
    0089 end
    0090
    0091 %adjust for Djui:
    0092 if isfield(Field,'DjUi')
    0093     Field.ListVarName(end-2:end)=[];
    0094     Field.ListVarName{end}='DjUi';
    0095     Field.VarDimIndex(end-2:end)=[];
    0096     Field.VarAttribute(end-2:end)=[];
    0097 end
    0098
    0099 %determine the appropriate constant for time and dt for the PIV pair
    0100 test_civ1=isequal(VelTypeOut,'civ1')||isequal(VelTypeOut,'interp1')||isequal(VelTypeOut,'filter1');
    0101 test_civ2=isequal(VelTypeOut,'civ2')||isequal(VelTypeOut,'interp2')||isequal(VelTypeOut,'filter2');
    0102 if test_civ1
    0103     Field.Time=Field.absolut_time_T0;
    0104 elseif test_civ2
    0105     Field.Time=Field.absolut_time_T0_2;
    0106     Field.dt=Field.dt2;
    0107 else
    0108     Field.Txt='the input file is not civx';
    0109     display(Field.Txt)
    0110 end
    0111
    0112 % CivStage
    0113 if isfield(Field,'patch2')&& isequal(Field.patch2,1)
    0114     Field.CivStage=6;
    0115 elseif isfield(Field,'fix2')&& isequal(Field.fix2,1)
    0116     Field.CivStage=5;
    0117 elseif isfield(Field,'civ2')&& isequal(Field.civ2,1)
    0118     Field.CivStage=4;
    0119 elseif isfield(Field,'patch')&& isequal(Field.patch,1)
    0120     Field.CivStage=3;
    0121 elseif isfield(Field,'fix')&& isequal(Field.fix,1)
    0122     Field.CivStage=2;
    0123 else
    0124     Field.CivStage=1;
    0125 end
    0126
    0127 %update list of global attributes
    0128 List=Field.ListGlobalAttribute;
    0129 ind_remove=[];
    0130 for ilist=1:length(List)
    0131     switch(List{ilist})
    0132         case {'patch2','fix2','civ2','patch','fix','dt2','absolut_time_T0','absolut_time_T0_2'}
    0133             ind_remove=[ind_remove ilist];
    0134             Field=rmfield(Field,List{ilist});
    0135     end
    0136 end
    0137 List(ind_remove)=[];
    0138 Field.ListGlobalAttribute=[List {'Time','CivStage','CoordUnit'}];
    0139
    0140 % rescale to pixel coordiantes
    0141 Field.U=Field.U*Field.pixcmx;
    0142 Field.V=Field.V*Field.pixcmy;
    0143 Field.X=Field.X*Field.pixcmx;
    0144 Field.Y=Field.Y*Field.pixcmy;
    0145 if ~isequal(Field.dt,0)
    0146     Field.U=Field.U*Field.dt;%translate in px displacement
    0147     Field.V=Field.V*Field.dt;
    0148     if isfield(Field,'DjUi')
    0149        Field.DjUi(:,1,1)=Field.dt*Field.DjUi(:,1,1);
    0150        Field.DjUi(:,2,2)=Field.dt*Field.DjUi(:,2,2);
    0151        Field.DjUi(:,1,2)=(Field.pixcmy/Field.pixcmx)*Field.dt*Field.DjUi(:,1,2);
    0152        Field.DjUi(:,2,1)=(Field.pixcmx/Field.pixcmy)*Field.dt*Field.DjUi(:,2,1);
    0153     end
    0154 end
    0155 Field.CoordType='px';% TODO: abandon, use COORdUnit instead ? (to adapt 'px' and 'phys')
    0156 Field.CoordUnit='pixel';
    0157
    0158
    0159 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    0160 % [var,role,units,vel_type_out]=varcivx_generator(FieldNames,vel_type)
    0161 %INPUT:
    0162 % FieldNames =cell of field names to get, which can contain the strings:
    0163 %             'ima_cor': image correlation, vec_c or vec2_C
    0164 %             'vort','div','strain': requires velocity derivatives DUDX...
    0165 %             'error': error estimate (vec_E or vec2_E)
    0166 %
    0167 % vel_type: character string indicating the types of velocity fields to read ('civ1','civ2'...)
    0168 %            if vel_type=[] or'*', a  priority choice, given by vel_type_out{1,2}, is done depending
    0169 %            if vel_type='filter'; a structured field is sought (filter2 in priority, then filter1)
    0170
    0171 function [var,role,units,vel_type_out]=varcivx_generator(FieldNames,vel_type)
    0172
    0173 %default input values
    0174 if ~exist('vel_type','var'),vel_type=[];end;
    0175 if iscell(vel_type),vel_type=vel_type{1}; end;%transform cell to string if needed
    0176 % if ~exist('display','var'),display=[];end;
    0177 if ~exist('FieldNames','var'),FieldNames={'ima_cor'};end;%default scalar
    0178 if ischar(FieldNames), FieldNames={FieldNames}; end;
    0179
    0180 %select the priority order for automatic vel_type selection
    0181 testder=0;
    0182 for ilist=1:length(FieldNames)
    0183     if ~isempty(FieldNames{ilist})
    0184     switch FieldNames{ilist}
    0185         case {'vort','div','strain'}
    0186             testder=1;
    0187     end
    0188     end
    0189 end
    0190 if isempty(vel_type) || isequal(vel_type,'*') %undefined velocity type (civ1,civ2...)
    0191     if testder
    0192          vel_type_out{1}='filter2'; %priority to filter2 for scalar reading, filter1 as second
    0193         vel_type_out{2}='filter1';
    0194     else
    0195         vel_type_out{1}='civ2'; %priority to civ2 for vector reading, civ1 as second priority
    0196         vel_type_out{2}='civ1';
    0197     end
    0198 elseif isequal(vel_type,'filter')
    0199         vel_type_out{1}='filter2'; %priority to filter2 for scalar reading, filter1 as second
    0200         vel_type_out{2}='filter1';
    0201         if ~testder
    0202             vel_type_out{3}='civ1';%civ1 as third priority if derivatives are not needed
    0203         end
    0204 elseif testder
    0205     test_civ1=isequal(vel_type,'civ1')||isequal(vel_type,'interp1')||isequal(vel_type,'filter1');
    0206     if test_civ1
    0207         vel_type_out{1}='filter1'; %switch to filter for reading spatial derivatives
    0208     else
    0209         vel_type_out{1}='filter2';
    0210     end
    0211 else
    0212     vel_type_out{1}=vel_type;%imposed velocity field
    0213 end
    0214 vel_type_out=vel_type_out';
    0215
    0216 %determine names of netcdf variables to read
    0217 var={'X','Y','Z','U','V','W','C','F','FF'};
    0218 role={'coord_x','coord_y','coord_z','vector_x','vector_y','vector_z','ancillary','warnflag','errorflag'};
    0219 units={'pixel','pixel','pixel','pixel','pixel','pixel',[],[],[]};
    0220 if testder
    0221     var=[var {'DjUi(:,1,1)','DjUi(:,1,2)','DjUi(:,2,1)','DjUi(:,2,2)'}];
    0222     role=[role {'tensor','tensor','tensor','tensor'}];
    0223     units=[units {'pixel','pixel','pixel','pixel'}];
    0224 end
    0225 for ilist=1:length(vel_type_out)
    0226     var=[var;varname1(vel_type_out{ilist},FieldNames)];
    0227 end
    0228
    0229
    0230 %-------------------------
    0231 %determine  var names to read
    0232 %--------------------------------------
    0233 function varin=varname1(vel_type,FieldNames)
    0234
    0235 testder=0;
    0236 C1='';
    0237 C2='';
    0238 for ilist=1:length(FieldNames)
    0239     if ~isempty(FieldNames{ilist})
    0240     switch FieldNames{ilist}
    0241         case 'ima_cor' %image correlation corresponding to a vel vector
    0242             C1='vec_C';
    0243             C2='vec2_C';
    0244         case 'error'
    0245             C1='vec_E';
    0246             C2='vec2_E';
    0247         case {'vort','div','strain'}
    0248             testder=1;
    0249     end
    0250     end
    0251 end
    0252 switch vel_type
    0253     case 'civ1'
    0254         varin={'vec_X','vec_Y','vec_Z','vec_U','vec_V','vec_W',C1,'vec_F','vec_FixFlag'};
    0255     case 'interp1'
    0256         varin={'vec_patch_X','vec_patch_Y','','vec_patch0_U','vec_patch0_V','','','',''};
    0257     case 'filter1'
    0258         varin={'vec_patch_X','vec_patch_Y','','vec_patch_U','vec_patch_V','','','',''};
    0259     case 'civ2'
    0260         varin={'vec2_X','vec2_Y','vec2_Z','vec2_U','vec2_V','vec2_W',C2,'vec2_F','vec2_FixFlag'};
    0261     case 'interp2'
    0262         varin={'vec2_patch_X','vec2_patch_Y','vec2_patch_Z','vec2_patch0_U','vec2_patch0_V','vec2_patch0_W','','',''};
    0263     case 'filter2'
    0264         varin={'vec2_patch_X','vec2_patch_Y','vec2_patch_Z','vec2_patch_U','vec2_patch_V','vec2_patch0_W','','',''};
    0265 end
    0266 if testder
    0267      switch vel_type
    0268         case 'filter1'
    0269             varin=[varin {'vec_patch_DUDX','vec_patch_DVDX','vec_patch_DUDY','vec_patch_DVDY'}];
    0270         case 'filter2'
    0271             varin=[varin {'vec2_patch_DUDX','vec2_patch_DVDX','vec2_patch_DUDY','vec2_patch_DVDY'}];
    0272     end
    0273 end