Impl week jse

Improved and updated tutorials in the toolbox for better understandability.

kernel/ClassStuff/@itaCoordinates/surf.m

-function varargout = surf(this, varargin)
+function varargout = surf(this, data, varargin)
 
 % <ITA-Toolbox>
 % This file is part of the ITA-Toolbox. Some rights reserved. 
@@ -6,12 +6,13 @@ function varargout = surf(this, varargin)
 % </ITA-Toolbox>
 
 
-% This function plots the surface of a itaCoordinates object c (or of one of
-% its children). Optionally the radius information r can be given explicitly.
+% This function plots the surface of an itaCoordinates object c (or of one of
+% its children). The second input 'data' determines the surface's colour
+% scheme. This could be for example the radius data.  
 % If the radius information is complex, it is regarded as a complex plot,
 % and the color is used to denote the phases.
 %
-% The plop parameter can be used for a upper limit of how much crazy
+% The plop parameter (see options) can be used for a upper limit of how much crazy
 % shaped triangulas will exist. A plop of 1 means only plot faces
 % that have smaller deformation as average. A factor of 4 makes sense for
 % most plots. Default is without plop (runs faster).
@@ -19,119 +20,96 @@ function varargout = surf(this, varargin)
 % All properties of the MATLAB built-in "Patch Properties" can be used.
 %
 % Syntax:
-%       surf(c)
+%       surf(c, data)
 %           plots the itaCoordinate object c
-%       surf(c,r)
-%           plots the radius r onto c
-%       surf(c,r,color)
-%           give the color explicitly
-%       surf(c,1,color)
-%           plots color data on the unit sphere
+%       surf(c, data, options)
+%           certain options (see below) can be set
 %       surf(c,r,color,'plop', 1, [optional parameter of built-in surf])
 %           opens the large triangles
-%       surf(c,ao,f)
-%           plots balloon of itaAudio object ao at frequency f
-%
 %           (other parameters are passed to the built-in surf function)
-%
-%
+
+% Options (default):
+%       'radius'    []      - sphere's radius
+%       'magnitude' (false)   - takes absolute value of data 
+%       'parent'    []
+%       'complex' (false)   - indicates if data is complex
+%       'colorbar'  (true)  - use colorbar scale
+%       'plop'      [] - regulation of triangle shapes 
+%       'hull'      [] - regulates shape's hull
+%             
 % Author:
 %   Martin Pollow, mpo@akustik.rwth-aachen.de, 4.1.2010
 
-
-defaultProperties = {'EdgeAlpha', 0, ...
-                     'FaceColor', 'interp'};
-
 sArgs             = struct('pos1_data','double', ...
                            'radius', [], ...
-                           'magnitude', 0, ...
+                           'magnitude', 0, ... 
                            'parent', [], ...
                            'complex', false, ...
-                           'colorbar', true, ...
-                           defaultProperties{:});
+                           'colorbar', true,...
+                           'plop', [],...
+                           'hull', []);
 
-[data,sArgs] = ita_parse_arguments(sArgs,varargin); 
+[data,sArgs] = ita_parse_arguments(sArgs, [data, varargin]); 
 
 if sArgs.magnitude
-   data = abs(data); 
+    data = abs(data);
 end
 
-%% now set r and color according to the input variables
-
-% there is three options for the colorbar settings:
-%   geometry / complex / magnitude
-% % check for a parent jri: I would like to make this pretty, but i don't
-% % have time
-% parent = 0;
-% if numel(varargin) && strcmpi(data,'Parent')
-%     parent = varargin{2};
-%     varargin = varargin(3:end);
-% end
-if (nargin == 1)
-    % only coordinates given
-    r = this.r;
-    color = zeros(size(r));
-    colorbar_settings = 'geometry';    
+%% now set radius and color according to the input variables
+% set radius
+if ~isempty(sArgs.radius)
+    r = sArgs.radius;
 else
-    % also a radius is given
-    if ~isempty(sArgs.radius)
-        r = sArgs.radius;
-    else
-        r = data.'; 
-    end
-    isComplex = ~all(isreal(r)) || sArgs.complex; 
-    if isComplex
-        if sArgs.complex && ~isempty(sArgs.radius)
-            color = mod(data,2*pi);
-        else
-            % if the radius is complex, set the color
-            color = mod(angle(r),2*pi);
-        end
-        colorbar_settings = 'complex';
+    r = data.';
+end
+
+% set colour - there are three options for the colorbar settings:
+% geometry / complex / magnitude
+isComplex = ~all(isreal(r)) || sArgs.complex;
+if isComplex
+    if sArgs.complex && ~isempty(sArgs.radius)
+        color = mod(data,2*pi);
     else
-        % if it is real, use the magnitude as color
-        color = r;
-%         ita_verbose_info('itaCoordinates.surf is plotting negative radius, take care',0);
-        colorbar_settings = 'magnitude';
+        % if the radius is complex, set the color
+        color = mod(angle(r),2*pi);
     end
-    r = abs(r);
-    
-    if ~isempty(sArgs.radius) && ~sArgs.complex
-        % if a color is given explicitly
-        % negative radii are set to 0
-        if sum(abs(imag(r))) > 0, ita_verbose_info('ignoring imaginary part of radius'); end
-        r = max(real(r),0);
-        color = data.';
-        % use the magnitude of complex data
-        if ~all(isreal(color))
-            color = abs(color);
-        end        
-        
-        colorbar_settings = 'magnitude';
+    colorbar_settings = 'complex';
+else
+    % if it is real, use the magnitude as color
+    color = r;
+    %         ita_verbose_info('itaCoordinates.surf is plotting negative radius, take care',0);
+    colorbar_settings = 'magnitude';
+end
+r = abs(r);
+
+if ~isempty(sArgs.radius) && ~sArgs.complex
+    % if a color is given explicitly
+    % negative radii are set to 0
+    if sum(abs(imag(r))) > 0, ita_verbose_info('ignoring imaginary part of radius'); end
+    r = max(real(r),0);
+    color = data.';
+    % use the magnitude of complex data
+    if ~all(isreal(color))
+        color = abs(color);
     end
-% elseif numArgIn > 2 && isa(data,'itaSuper')
-%     varargout{1} = surf(this, data.freq2value(varargin{2}), varargin{3:end});
-%     title([' f = ' num2str(varargin{2}) 'Hz '])
-%     if ~nargout, varargout = {}; end
-%     return;
+
+    colorbar_settings = 'magnitude';
 end
 
 % define how big the patches can get
-if numel(varargin) && strcmpi(data,'plop')
-    maxAreaVertex = varargin{2};
-    varargin = varargin(3:end);
+if ~isempty(sArgs.plop) 
+    maxAreaVertex = sArgs.plop;
 else
     maxAreaVertex = 0;
 end
 
 
-% set a hull if no is explicitly given
-if numel(varargin) && strcmpi(data,'hull')
-    hull = varargin{2};
+% set a hull 
+if ~isempty(sArgs.hull) 
+    hull = sArgs.hull;
     if any(size(hull,2) ~= 3)
         error('something wrong with the hull in itaCoordinates.surf');
     end
-    varargin = varargin(3:end);
 else
     % use unity radius to create triangularisation
     this.r = 1;
@@ -191,10 +169,7 @@ else
     set(hFig, 'FaceVertexCData', color(:));
 end
 set(gca,'SortMethod','depth'); % replaced set(gca,'DrawMode','fast'); % this avoids a MATLAB segfault (?? only for renderer painters)
-set(hFig, defaultProperties{:});
-% if numel(varargin)
-%     set(hFig, varargin{:});
-% end
+set(hFig);
 
 switch colorbar_settings
     case 'geometry'