1 ## Copyright (C) 2004 Josep Mones i Teixidor
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 ## Based on old imadjust.m (GPL):
18 ## Copyright (C) 1999,2000 Kai Habel
22 ## @deftypefn {Function File} @var{J}= imadjust (@var{I})
23 ## @deftypefnx {Function File} @var{J}= imadjust (@var{I},[@var{low_in};@var{high_in}])
24 ## @deftypefnx {Function File} @var{J}= imadjust (@var{I},[@var{low_in};@var{high_in}],[@var{low_out};@var{high_out}])
25 ## @deftypefnx {Function File} @var{J}= imadjust (..., @var{gamma})
26 ## @deftypefnx {Function File} @var{newmap}= imadjust (@var{map}, ...)
27 ## @deftypefnx {Function File} @var{RGB_out}= imadjust (@var{RGB}, ...)
28 ## Adjust image or colormap values to a specified range.
30 ## @code{J=imadjust(I)} adjusts intensity image @var{I} values so that
31 ## 1% of data on lower and higher values (2% in total) of the image is
32 ## saturated; choosing for that the corresponding lower and higher
33 ## bounds (using @code{stretchlim}) and mapping them to 0 and 1. @var{J}
34 ## is an image of the same size as @var{I} which contains mapped values.
35 ## This is equivalent to @code{imadjust(I,stretchlim(I))}.
37 ## @code{J=imadjust(I,[low_in;high_in])} behaves as described but uses
38 ## @var{low_in} and @var{high_in} values instead of calculating them. It
39 ## maps those values to 0 and 1; saturates values lower than first limit
40 ## to 0 and values higher than second to 1; and finally maps all values
41 ## between limits linearly to a value between 0 and 1. If @code{[]} is
42 ## passes as @code{[low_in;high_in]} value, then @code{[0;1]} is taken
43 ## as a default value.
45 ## @code{J=imadjust(I,[low_in;high_in],[low_out;high_out])} behaves as
46 ## described but maps output values between @var{low_out} and
47 ## @var{high_out} instead of 0 and 1. A default value @code{[]} can also
48 ## be used for this parameter, which is taken as @code{[0;1]}.
50 ## @code{J=imadjust(...,gamma)} takes, in addition of 3 parameters
51 ## explained above, an extra parameter @var{gamma}, which specifies the
52 ## shape of the mapping curve between input elements and output
53 ## elements, which is linear (as taken if this parameter is omitted). If
54 ## @var{gamma} is above 1, then function is weighted towards lower
55 ## values, and if below 1, towards higher values.
57 ## @code{newmap=imadjust(map,...)} applies a transformation to a
58 ## colormap @var{map}, which output is @var{newmap}. This transformation
59 ## is the same as explained above, just using a map instead of an image.
60 ## @var{low_in}, @var{high_in}, @var{low_out}, @var{high_out} and
61 ## @var{gamma} can be scalars, in which case the same values are applied
62 ## for all three color components of a map; or it can be 1-by-3
63 ## vectors, to define unique mappings for each component.
65 ## @code{RGB_out=imadjust(RGB,...)} adjust RGB image @var{RGB} (a
66 ## M-by-N-by-3 array) the same way as specified in images and colormaps.
67 ## Here too @var{low_in}, @var{high_in}, @var{low_out}, @var{high_out} and
68 ## @var{gamma} can be scalars or 1-by-3 matrices, to specify the same
69 ## mapping for all planes, or unique mappings for each.
71 ## The formula used to realize the mapping (if we omit saturation) is:
73 ## @code{J = low_out + (high_out - low_out) .* ((I - low_in) / (high_in - low_in)) .^ gamma;}
75 ## @strong{Compatibility notes:}
79 ## Prior versions of imadjust allowed @code{[low_in; high_in]} and
80 ## @code{[low_out; high_out]} to be row vectors. Compatibility with this
81 ## behaviour has been keeped, although preferred form is vertical vector
82 ## (since it extends nicely to 2-by-3 matrices for RGB images and
85 ## Previous version of imadjust, if @code{low_in>high_in} it "negated" output.
86 ## Now it is negated if @code{low_out>high_out}, for compatibility with
89 ## Class of @var{I} is not considered, so limit values are not
90 ## modified depending on class of the image, just treated "as is". When
91 ## Octave 2.1.58 is out, limits will be multiplied by 255 for uint8
92 ## images and by 65535 for uint16 as in MATLAB.
95 ## @seealso{stretchlim, brighten}
98 ## Author: Josep Mones i Teixidor <jmones@puntbarra.com>
100 ## TODO: When Octave 2.1.58 is out multiply indices if input argument is
101 ## TODO: of class int* or uint*.
103 function ret = imadjust (image, in, out, gamma)
105 if (nargin < 1 || nargin > 4)
106 usage ("imadjust(...) number of arguments must be between 1 and 4");
110 gamma = 1; ## default gamma
113 if !(ismatrix(image))
114 error ("imadjust(image,...) first parameter must be a image matrix or colormap");
118 in=stretchlim(image); ## this saturates 1% on lower and 1% on
119 out=[0;1]; ## higher values
123 out=[0;1]; ## default out
126 if !((ismatrix(in) || isempty(in)) && (ismatrix(out) || isempty(out)) )
127 usage("imadjust(image,[low high],[bottom top],gamma)");
131 in=[0;1]; ## default in
135 out=[0;1]; ## default out
139 if (length(simage)==3 && simage(3)==3)
141 [in, out, gamma]=__imadjust_check_3d_args__(in, out, gamma);
144 ret=zeros(size(image));
146 ## process each plane
148 ret(:,:,i)=__imadjust_plane__(image(:,:,i),in(1,i),in(2,i),out(1,i),out(2,i),gamma(1,i));
151 elseif (length(simage)==2)
153 (size(in)==[2,3] || size(out)==[2,3] || size(gamma)==[1,3]) )
154 ## image is a colormap
155 [in, out, gamma]=__imadjust_check_3d_args__(in, out, gamma);
158 ## process each color
160 ret=horzcat(ret,__imadjust_plane__(image(:,i),in(1,i),in(2,i),out(1,i),out(2,i),gamma(i)));
164 ## image is a intensity image
165 if( !isvector(in) || length(in)!=2 || !isvector(out) || length(out)!=2 || !isscalar(gamma) || (gamma<0) || (gamma==Inf) )
166 error("imadjust: on an intensity image, in and out must be 2-by-1 and gamma a positive scalar.");
168 ret=__imadjust_plane__(image,in(1),in(2),out(1),out(2),gamma);
172 error("imadjust: first parameter must be a colormap, an intensity image or a RGB image");
177 ## This does all the work. I has a plane; li and hi input low and high
178 ## values; and lo and ho, output bottom and top values.
179 ## Image negative is computed if ho<lo although nothing special is
180 ## needed, since formula automatically handles it.
181 function ret=__imadjust_plane__(I, li, hi, lo, ho, gamma)
182 ret = (I < li) .* lo;
183 ret = ret + (I >= li & I < hi) .* (lo + (ho - lo) .* ((I - li) / (hi - li)) .^ gamma);
184 ret = ret + (I >= hi) .* ho;
188 ## Checks in, out and gamma to see if they are ok for colormap and RGB
190 function [in, out, gamma]=__imadjust_check_3d_args__(in, out, gamma)
196 case([1,2]) ## Compatibility behaviour!
199 error("imadjust: in must be 2-by-3 or 2-by-1.");
207 case([1,2]) ## Compatibility behaviour!
208 out=repmat(out',1,3);
210 error("imadjust: out must be 2-by-3 or 2-by-1.");
217 gamma=repmat(gamma,1,3);
219 error("imadjust: gamma must be a scalar or a 1-by-3 matrix.");
222 ## check gamma allowed range
223 if(!all((gamma>=0)&(gamma<Inf)))
224 error("imadjust: gamma values must be in the range [0,Inf]");
233 %!error(imadjust("bad argument"));
234 %!error(imadjust(zeros(10,10,3,2)));
235 %!error(imadjust(zeros(10,10,4)));
236 %!error(imadjust("bad argument"));
238 # bad 2d, 3d or 4th argument
239 %!error(imadjust([1:100],"bad argument",[0;1],1));
240 %!error(imadjust([1:100],[0,1,1],[0;1],1));
241 %!error(imadjust([1:100],[0;1],[0,1,1],1));
242 %!error(imadjust([1:100],[0;1],[0;1],[0;1]));
243 %!error(imadjust([1:100],[0;1],[0;1],-1));
245 %!# 1% on each end saturated
246 %!assert(imadjust([1:100]),[0,linspace(0,1,98),1]);
248 %!# test with only input arg
249 %!assert(sum(abs((imadjust(linspace(0,1,100),[1/99;98/99]) - \
250 %! [0,linspace(0,1,98),1] )(:))) < 1e-10);
252 %!# a test with input and output args
253 %!assert(imadjust([1:100],[50;90],[-50;-30]), \
254 %! [-50*ones(1,49), linspace(-50,-30,90-50+1), -30*ones(1,10)]);
256 %!# a test with input and output args in a row vector (Compatibility behaviour)
257 %!assert(imadjust([1:100],[50,90],[-50,-30]), \
258 %! [-50*ones(1,49), linspace(-50,-30,90-50+1), -30*ones(1,10)]);
260 %!# the previous test, "negated"
261 %!assert(imadjust([1:100],[50;90],[-30;-50]), \
262 %! [-30*ones(1,49), linspace(-30,-50,90-50+1), -50*ones(1,10)]);
266 %! cm=[[1:10]',[2:11]',[3:12]'];
267 %! cmn=([[1:10]',[2:11]',[3:12]']-1)/11;
270 %!assert(imadjust(cmn,[0;1],[10;11]),cmn+10);
272 %!# a colormap with params in row (Compatibility behaviour)
273 %!assert(imadjust(cmn,[0,1],[10,11]),cmn+10);
275 %!# a colormap, different output on each
276 %!assert(imadjust(cmn,[0;1],[10,20,30;11,21,31]),cmn+repmat([10,20,30],10,1));
278 %!# a colormap, different input on each, we need increased tolerance for this test
279 %!assert(sum(abs((imadjust(cm,[2,4,6;7,9,11],[0;1]) - \
280 %! [[0,linspace(0,1,6),1,1,1]', \
281 %! [0,0,linspace(0,1,6),1,1]', \
282 %! [0,0,0,linspace(0,1,6),1]'] \
286 %!# a colormap, different input and output on each
287 %!assert(sum(abs((imadjust(cm,[2,4,6;7,9,11],[0,1,2;1,2,3]) - \
288 %! [[0,linspace(0,1,6),1,1,1]', \
289 %! [0,0,linspace(0,1,6),1,1]'+1, \
290 %! [0,0,0,linspace(0,1,6),1]'+2] \
294 %!# a colormap, different gamma, input and output on each
295 %!assert(sum(abs((imadjust(cm,[2,4,6;7,9,11],[0,1,2;1,2,3],[1,2,3]) - \
296 %! [[0,linspace(0,1,6),1,1,1]', \
297 %! [0,0,linspace(0,1,6).^2,1,1]'+1, \
298 %! [0,0,0,linspace(0,1,6).^3,1]'+2] \
303 %!shared iRGB,iRGBn,oRGB
304 %! iRGB=zeros(10,1,3);
305 %! iRGB(:,:,1)=[1:10]';
306 %! iRGB(:,:,2)=[2:11]';
307 %! iRGB(:,:,3)=[3:12]';
308 %! iRGBn=(iRGB-1)/11;
309 %! oRGB=zeros(10,1,3);
310 %! oRGB(:,:,1)=[0,linspace(0,1,6),1,1,1]';
311 %! oRGB(:,:,2)=[0,0,linspace(0,1,6),1,1]';
312 %! oRGB(:,:,3)=[0,0,0,linspace(0,1,6),1]';
315 %!assert(imadjust(iRGBn,[0;1],[10;11]),iRGBn+10);
317 %!# a RGB image, params in row (compatibility behaviour)
318 %!assert(imadjust(iRGBn,[0,1],[10,11]),iRGBn+10);
320 %!# a RGB, different output on each
326 %! assert(imadjust(iRGBn,[0;1],[10,20,30;11,21,31]),t);
329 %!# a RGB, different input on each, we need increased tolerance for this test
330 %!assert(sum(abs((imadjust(iRGB,[2,4,6;7,9,11],[0;1]) - oRGB)(:))) < 1e-10);
332 %!# a RGB, different input and output on each
337 %! assert(sum(abs((imadjust(iRGB,[2,4,6;7,9,11],[0,1,2;1,2,3]) - t)(:))) < 1e-10);
339 %!# a RGB, different gamma, input and output on each
342 %! t(:,:,2)=t(:,:,2).^2+1;
343 %! t(:,:,3)=t(:,:,3).^3+2;
344 %! assert(sum(abs((imadjust(iRGB,[2,4,6;7,9,11],[0,1,2;1,2,3],[1,2,3]) - t)(:))) < 1e-10);
349 % Revision 1.3 2007/03/23 16:14:37 adb014
350 % Update the FSF address
352 % Revision 1.2 2007/01/04 23:47:43 hauberg
353 % Put seealso before end deftypefn
355 % Revision 1.1 2006/08/20 12:59:33 hauberg
356 % Changed the structure to match the package system
358 % Revision 1.3 2004/09/01 22:51:14 jmones
359 % Fully recoded: NDArray support, docs, tests, more compatible with MATLAB, changed copyright