Merge pull request #74 from sfstoolbox/change_removedelay_wording

Change removedelay wording

NEWS

@@ -12,7 +12,7 @@ Changes in the Sound Field Synthesis-Toolbox. Recent changes on top.
     - rename chromajs colormap to yellowred
     - fix tapering_window() for non-continuous secondary sources
     - remove cubehelix colormap as it is part of Octave
-    - add conf.wfs.removedelay option with is useful, if you have more than one
+    - add conf.wfs.t0 option with is useful, if you have more than one
       virtual source
     - virtual line sources are now available for monochromatic WFS and NFC-HOA
     - allow arbritrary orders for time-domain NFC-HOA simulations

README.md

@@ -484,11 +484,11 @@ conf.plot.colormap = 'jet'; % Matlab rainbow color map
 If you want to simulate more than one virtual source, it is a good idea to set
 the starting time of your simulation to start with the activity of your virtual
 source and not the secondary sources, which is the default behavior. You can
-change this by setting `conf.wfs.removedelay = false`.
+change this by setting `conf.wfs.t0 = 'source'`.
 
 ```Matlab
 conf.plot.useplot = false;
-conf.wfs.removedelay = false;
+conf.wfs.t0 = 'source';
 t_40cm = round(0.4/conf.c*conf.fs); % in samples
 [p_ps,~,~,~,x0_ps] = ...
     sound_field_imp_wfs([-2 2],[-2 2],0,[1.9 0 0],'ps',20+t_40cm,conf);

SFS_config.m

@@ -222,11 +222,20 @@
 conf.wfs.hpreFIRorder = 128; % even integer
 %
 % === Time Domain Implementation ===
-% Remove the leading delay in WFS-time domain driving function.
-% If this is set to true, the first active secondary source will be start to
-% emit sound at t = 1.
-% (convenient behaviour for a single virtual source)
-conf.wfs.removedelay = true; % boolean
+% Adjust the starting time in WFS-time domain driving functions.
+% This can be set to
+%   'system'   - the first secondary source will be active at t=0
+%   'source'   - the virtual source will be active at t=0
+% Setting it to 'system' is most convenient when simulating single sources as
+% you will always see activity in the sound field for t>0. Setting it to
+% 'source' helps you to simulate different sources as you can time align them
+% easily. Note, that for virtual sources outside of the array this can mean you
+% will see no activity inside the listening area until the time has passed, that
+% the virtual source needs from its position until the nearest secondary source.
+% (Also note, using 'source' for systems with unbounded listening areas, (e.g.
+% linear arrays), focussed virtual sources may not be placed arbitrarily
+% far from the secondary sources.)
+conf.wfs.t0 = 'system'; % string
 
 
 %% ===== Spectral Division Method (SDM) ==================================

SFS_time_domain/driving_function_imp_wfs.m

@@ -75,7 +75,7 @@
 fs = conf.fs;
 N = conf.N;
 c = conf.c;
-removedelay = conf.wfs.removedelay;
+t0 = conf.wfs.t0;
 
 
 %% ===== Computation =====================================================
@@ -112,13 +112,13 @@
     error('%s: %s is not a known source type.',upper(mfilename),src);
 end
 
-if removedelay
-    % Set minimum delay to 0, in order to begin always at t=0 with the first
+if strcmp('system',t0)
+    % Set minimum delay to 0, in order to begin always at t=1 with the first
     % wave front at any secondary source
     delay = delay - min(delay);
     % Return extra offset due to prefilter
     delay_offset = prefilter_delay;
-else
+elseif strcmp('source',t0)
     % Add extra delay to ensure causality at all secondary sources (delay>0)
     [diameter,center] = secondary_source_diameter(conf);
     t0 = diameter/c;
@@ -139,6 +139,9 @@
     % Return extra added delay. This is can be used to ensure that the virtual
     % source always starts at t = 0.
     delay_offset = t0 + prefilter_delay;
+else
+    error('%s: t0 needs to be "system" or "source" and not "%s".', ...
+          upper(mfilename),t0);
 end
 % Append zeros at the end of the driving function. This is necessary, because
 % the delayline function cuts into the end of the driving signals in order to

doc/img/generate_README_plots.m

@@ -176,7 +176,7 @@
 plot_sound_field(p,[-2 2],[-2 2],0,x0,conf);
 print_png('sound_field_imp_nfchoa_25d_dB.png');
 conf.plot.useplot = false;
-conf.wfs.removedelay = false;
+conf.wfs.t0 = 'source';
 t_40cm = round(0.4/conf.c*conf.fs); % in samples
 [p_ps,~,~,~,x0_ps] = ...
     sound_field_imp_wfs([-2 2],[-2 2],0,[1.9 0 0],'ps',20+t_40cm,conf);

validation/test_driving_functions_imp_with_delay.m

@@ -1,6 +1,6 @@
 function boolean = test_driving_functions_imp_with_delay(modus)
 %TEST_DRIVING_FUNCTIONS_IMP_WITH_DELAY tests the correctness of the time-domain
-%driving functions, in the case of conf.wfs.removedelay=false
+%driving functions, in the case of conf.wfs.t0 = 'source'
 %
 %   Usage: boolean = test_driving_functions_imp_with_delay(modus)
 %
@@ -13,7 +13,7 @@
 %
 %   TEST_DRIVING_FUNCTIONS_IMP_WITH_DELAY(MODUS) checks if the functions,
 %   that calculates the WFS driving functions in time-domain work correctly
-%   for the setting conf.wfs.removedelay = false.
+%   for the setting conf.wfs.t0 = 'source'.
 %   Therefore different sound fields are simulated.
 
 %*****************************************************************************
@@ -59,7 +59,7 @@
 
 %% ===== Configuration ===================================================
 conf = SFS_config;
-conf.wfs.removedelay = false;
+conf.wfs.t0 = 'source';
 conf.secondary_sources.size = 3;
 conf.plot.useplot = false;
 conf.plot.usenormalisation = true;