1 ## Copyright (C) 1999 Paul Kienzle
3 ## This program is free software; you can redistribute it and/or modify
4 ## it under the terms of the GNU General Public License as published by
5 ## the Free Software Foundation; either version 2 of the License, or
6 ## (at your option) any later version.
8 ## This program is distributed in the hope that it will be useful,
9 ## but WITHOUT ANY WARRANTY; without even the implied warranty of
10 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 ## GNU General Public License for more details.
13 ## You should have received a copy of the GNU General Public License
14 ## along with this program; If not, see <http://www.gnu.org/licenses/>.
17 ## @deftypefn {Function File} {[@var{y},@var{t},@var{scale}] = } auplot (@var{x})
18 ## @deftypefnx {Function File} {[@var{y},@var{t},@var{scale}] = } auplot (@var{x},@var{fs})
19 ## @deftypefnx {Function File} {[@var{y},@var{t},@var{scale}] = } auplot (@var{x},@var{fs},@var{offset})
20 ## @deftypefnx {Function File} {[@var{y},@var{t},@var{scale}] = } auplot (@var{...},@var{plotstr})
22 ## Plot the waveform data, displaying time on the @var{x} axis. If you are
23 ## plotting a slice from the middle of an array, you may want to specify
24 ## the @var{offset} into the array to retain the appropriate time index. If
25 ## the waveform contains multiple channels, then the data are scaled to
26 ## the range [-1,1] and shifted so that they do not overlap. If a @var{plotstr}
27 ## is given, it is passed as the third argument to the plot command. This
28 ## allows you to set the linestyle easily. @var{fs} defaults to 8000 Hz, and
29 ## @var{offset} defaults to 0 samples.
31 ## Instead of plotting directly, you can ask for the returned processed
32 ## vectors. If @var{y} has multiple channels, the plot should have the y-range
33 ## [-1 2*size(y,2)-1]. scale specifies how much the matrix was scaled
34 ## so that each signal would fit in the specified range.
36 ## Since speech samples can be very long, we need a way to plot them
37 ## rapidly. For long signals, auplot windows the data and keeps the
38 ## minimum and maximum values in the window. Together, these values
39 ## define the minimal polygon which contains the signal. The number of
40 ## points in the polygon is set with the global variable auplot_points.
41 ## The polygon may be either 'filled' or 'outline', as set by the global
42 ## variable auplot_format. For moderately long data, the window does
43 ## not contain enough points to draw an interesting polygon. In this
44 ## case, simply choosing an arbitrary point from the window looks best.
45 ## The global variable auplot_window sets the size of the window
46 ## required for creating polygons. You can turn off the polygons
47 ## entirely by setting auplot_format to 'sampled'. To turn off fast
48 ## plotting entirely, set auplot_format to 'direct', or set
49 ## auplot_points=1. There is no reason to do this since your screen
50 ## resolution is limited and increasing the number of points plotted
51 ## will not add any information. auplot_format, auplot_points and
52 ## auplot_window may be set in .octaverc. By default auplot_format is
53 ## 'outline', auplot_points=1000 and auplot_window=7.
56 ## 2000-03 Paul Kienzle
57 ## accept either row or column data
58 ## implement fast plotting
59 ## 2000-04 Paul Kienzle
60 ## return signal and time vectors if asked
62 ## TODO: test offset and plotstr
63 ## TODO: convert offset to time range in the form used by au
64 ## TODO: rename to au; if nargout return data within time range
65 ## TODO: otherwise plot the data
66 function [y_r, t_r, scale_r] = auplot(x, fs, offset, plotstr)
68 global auplot_points=1000;
69 global auplot_format="outline";
70 global auplot_window=7;
72 if nargin<1 || nargin>4
73 usage("[y, t, scale] = auplot(x [, fs [, offset [, plotstr]]])");
75 if nargin<2, fs = 8000; offset=0; plotstr = []; endif
76 if nargin<3, offset=0; plotstr = []; endif
77 if nargin<4, plotstr = []; endif
78 if ischar(fs), plotstr=fs; fs=8000; endif
79 if ischar(offset), plotstr=offset; offset=0; endif
80 if isempty(plotstr), plotstr=";;"; endif
83 if (size(x,1)<size(x,2)), x=x'; endif
85 [samples, channels] = size(x);
86 r = ceil(samples/auplot_points);
88 hastail = (samples>c*r);
90 if r==1 || strcmp(auplot_format,"direct")
92 t=[0:samples-1]*1000/fs;
94 elseif r<auplot_window || strcmp(auplot_format,"sampled")
97 t=[0:size(y,1)-1]*1000*r/fs;
98 elseif strcmp(auplot_format,"filled")
102 y=zeros(2*(c+1),channels);
103 t(2*c+1)=t(2*c+2)=c*1000*r/fs;
106 y=zeros(2*c,channels);
108 t(1:2:2*c) = t(2:2:2*c) = [0:c-1]*1000*r/fs;
110 head=reshape(x(1:r*c,chan),r,c);
111 y(1:2:2*c,chan) = max(head)';
112 y(2:2:2*c,chan) = min(head)';
114 tail=x(r*c+1:samples,chan);
115 y(2*c+1,chan)=max(tail);
116 y(2*c+2,chan)=min(tail);
119 elseif strcmp(auplot_format,"outline")
122 y=zeros(2*(c+1)+1,channels);
125 y=zeros(2*c+1,channels);
128 t=[t, fliplr(t), 0]*1000*r/fs;
130 head=reshape(x(1:r*c,chan),r,c);
132 tail=x(r*c+1:samples,chan);
133 y(:,chan)=[max(head), max(tail), min(tail), \
134 fliplr(min(head)), max(head(:,1))]';
136 y(:,chan)=[max(head), fliplr(min(head)), max(head(:,1))]';
140 error("auplot_format must be 'outline', 'filled', 'sampled' or 'direct'");
146 scale = max(abs(y(:)));
147 if (scale > 0) y=y/scale; endif
149 y(:,i) = y(:,i) + 2*(i-1);
155 if nargout >= 1, y_r = y; endif
156 if nargout >= 2, t_r = t; endif
157 if nargout >= 3, scale_r = scale; endif
160 unwind_protect ## protect plot state
161 ylabel(sprintf('signal scaled by %f', scale));
162 axis([min(t), max(t), -1, 2*channels-1]);
164 unwind_protect_cleanup
174 %! [x, fs] = auload(file_in_loadpath("sample.wav"));
175 %! subplot(211); title("single channel"); auplot(x,fs);
176 %! subplot(212); title("2 channels, x and 3x"); auplot([x, 3*x], fs);
177 %! oneplot(); title("");
180 %! [x, fs] = auload(file_in_loadpath("sample.wav"));
181 %! global auplot_points; pts=auplot_points;
182 %! global auplot_format; fmt=auplot_format;
183 %! auplot_points=300;
184 %! subplot(221); title("filled"); auplot_format="filled"; auplot(x,fs);
185 %! subplot(223); title("outline"); auplot_format="outline"; auplot(x,fs);
186 %! auplot_points=900;
187 %! subplot(222); title("sampled"); auplot_format="sampled"; auplot(x,fs);
188 %! subplot(224); title("direct"); auplot_format="direct"; auplot(x,fs);
189 %! auplot_format=fmt; auplot_points=pts; title(""); oneplot();
192 %! [x, fs] = auload(file_in_loadpath("sample.wav"));
193 %! title("subrange example"); auplot(au(x,fs,300,450),fs)
197 %!error auplot(1,2,3,4,5)