1function [s,M,H] = cspy (A,res)
2%CSPY plot a matrix in color.
3%   cspy(A) plots a matrix, in color, with a default resolution of
4%   256-by-256.  cspy(A,res) changes the resolution to res.  Zero entries are
5%   white.  Entries with tiny absolute value are light orange.  Entries with
6%   large magnitude are black.  Entries in the midrange (the median of the
7%   log10 of the nonzero values, +/- one standard deviation) range from light
8%   green to deep blue.  With no inputs, the color legend of cspy is plotted.
9%   [s,M,H] = cspy(A) returns the scale factor s, the image M, and colormap H.
10%
11%   The matrix A can be full or sparse, and either numeric (double, single,
12%   integer) or character type, and either complex or real.
13%
14%   Example
15%       A = delsq (numgrid ('L', 10)) ;
16%       cspy (A) ;
17%
18%   See also CS_DMSPY, SPY.
19
20% Copyright 2006-2012, Timothy A. Davis, http://www.suitesparse.com
21
22if nargin < 2
23    res = 256 ;
24end
25
26h = jet (64) ;
27h = h (64:-1:1,:) ;
28h = h (30:end,:) ;
29hmax = size (h,1) ;
30
31h (1,:)  = [1 1 1] ;    % white for zero
32h (2,:)  = [1 .9 .5] ;  % light orange for tiny entries
33h (hmax,:) = [0 0 0] ;  % black for very large entries
34colormap (h) ;
35
36if (nargin == 0)
37    image (1:hmax) ;
38    title ('cspy color map') ;
39    return
40end
41
42% convert complex, integers, and strings to real double
43if (~isreal (A) | ~isa (A, 'double') | ~issparse (A))                       %#ok
44    A = sparse (abs (double (A))) ;
45end
46
47[m1 n1] = size (A) ;
48if (m1 == 0 | n1 == 0)                                                      %#ok
49    A (1,1) = 0 ;
50end
51[m1 n1] = size (A) ;
52
53S = cs_thumb (A,res) ;      % get the thumbnail of the matrix
54[m n] = size (S) ;
55[i j x] = find (S) ;
56x = log10 (x) ;
57
58if (isempty (x))
59    S = zeros (size (S)) ;
60else
61    med = median (x) ;
62    sdev = std (x) ;
63    big = med + sdev ;
64    tiny = med - sdev ;
65    imid = find (x > tiny & x < big) ;
66    itiny = find (x <= tiny) ;
67    ibig = find (x >= big) ;
68    x (imid) = 1 + ceil ((hmax-2) * (x (imid) - tiny) / (big - tiny)) ;
69    x (itiny) = 1 ;                                                         %#ok
70    x (ibig) = hmax-1 ;                                                     %#ok
71    S = full (1 + sparse (i,j,x,m,n)) ;
72
73%   title (sprintf ('tiny: %-8.2g   median: %-8.2g   big: %-8.2g\n', ...
74%       10^tiny, 10^med, 10^big)) ;
75end
76
77% draw the matrix
78image (S) ;
79axis equal ;
80axis ([-1 n+1 -1 m+1]) ;
81axis off
82
83% draw a box around the whole matrix
84e = ceil (max (m1,n1) / max (m,n)) ;    % scale factor
85hold on
86drawbox (1,m1+1,1,n1+1,'k',1,e) ;
87hold off
88
89% return results
90if (nargout > 0)
91    s = e ;
92end
93if (nargout > 1)
94    M = S ;             % image
95end
96if (nargout > 2)
97    H = h ;             % colormap
98end
99
100