function  Hparams = Hinton_params(spec)

%HINTON_PARAMS -- Specification of a Hinton diagram (see HINTON_DIAG).
%
%  Hparams = Hinton_params
%  Hparams = Hinton_params(seed_params)
%  Hparams = Hinton_params(mode)
%
%  SPEC is either a 'seed' structure or one of the following strings:
%   'hot1'   -- hot color diagram with 64 levels, range= [0:+1], default.
%   'jet1'   -- jet color diagram with 64 levels, range= [0:+1].
%   'color2' -- coldhot color diagram with 64 levels, range=[-1:+1].
%   'gray1'  -- grayscale diagram w/ 64 levels, range= [0:+1], 0=black.
%   'gray2'  -- grayscale diagram w/ 64 levels, range=[-1:+1], 0=gray.
%   'frame'  -- grayscale diagram w/ 64 levels, range= [0:+1], 0=white.
%   'fill'   -- B/W fill  diagram w/ 24 levels, range= [0:+1]
%  The one-branch (positive only) diagrams are suitable for activation
%  patterns; the two-branch ones are suitable for weight matrices.
%
%  HPARAMS is a structure with the following fields:
%    rep_sz: [7 5]      % representation size (see PLFRONTEND)
%    elt_sz: [5 5]      % size of each element [pixels]
%   canv_sz: [52 71]    % size of the whole diagram [pixels]
%  D_orient: [1x7]      % degrees clockwise from vertical
%   D_radii: [1x5]      % a set of sectors
%    colors=            % color structure
%        mode: 'hot1'     % mode
%        zero: 1          % index of the color coding for DATA=0
%        span: 63         % = max_index - zero
%        canv: 1          % background (canvas) color index
%         map: [64x3]     % colormap
%        colorbar: 'vert' % 'vert','horiz', or 'off', see COLORBAR
%        [fill,nofill]    % used in 'fill' mode only
%        ordinate: 0      % draw no vertical line at theta=0
%      axis=            % axis ticks and labels, see SET(GCA,...)
%        xtick: [1x7]
%        ytick: [1x5]
%        xticklabel: '-45|-30|-15|0|+15|+30|+45'  % degrees from vertical
%        yticklabel: '1.0|1.4|2.0|2.8|4.0'        % cycles per degree.v.a
%   mapping: [35x25]    % canvas(mapping(:)) = data(:) ...
%     frame:            % optional: canvas(frame(:)) = colors.frame ...
%
%  Example:
%   Hparams = Hinton_params ; N = prod(Hparams.rep_sz) ;
%   data = [1:N]' ; Hinton_diag(data,Hparams) ;
%
%  See also HINTON_DIAG, PLM_INPUT_PARAMS, COLORMAP, COLDHOT, IMAGESC.

%  Original coding by Alexander Petrov, UC Irvine.
%  $Revision: 1.3 $  $Date: 2003/06/24 17:07 $

%---  Decipher SPEC and supply defaults
if (nargin==0)
  spec = 'hot1' ;      % default
end

D_orient = [-15:5:+15] ;
XTickLabel = '-45|-30|-15|0|+15|+30|+45' ;  % degrees from vertical
D_radii  = [1:5].*10 + 68 ;  % calibrated for rep_sz=[7,5] and elt_sz=[5,5]
YTickLabel = '1.0|1.4|2.0|2.8|4.0' ;        % cycles per degree.v.a
elt_sz = [5 5] ;
canv_sz = [0,0] ;      % expanded later

if (ischar(spec))      % color specification
  switch  lower(spec)
  case 'jet1'        % range = [0:+1] ; colormap jet
    colors.mode = 'jet1' ;
    colors.zero = 2 ;    % blue
    colors.span = 62 ;   % max = 2+62 = 64 = dark red
    colors.canv = 1 ;    % light gray -- see below
    colors.map  = jet(64) ;  % COLORMAP(jet)
    colors.map(colors.canv,:) = [0.7,0.7,0.7] ;
  case 'hot1'        % range = [0:+1] ; colormap hot
    colors.mode = 'hot1' ;
    colors.zero = 2 ;    % black
    colors.span = 62 ;   % max = 2+62 = 64 = white
    colors.canv = 1 ;    % light blue -- see below
    colors.map  = [[0,0.7,1] ; [0 0 0;hot(62)]] ;  % COLORMAP(hot)
  case 'coldhot2'        % range = [-1:+1] ; colormap coldhot
    colors.mode = 'coldhot2' ;
    colors.zero = 33 ;   % black
    colors.span = 31 ;   % max = 31+33 = 64 = dark red
    colors.canv = 1 ;    % light gray
    colors.map  = [[0.7,0.7,0.7] ; coldhot(63)] ;  % COLORMAP(coldhot)
  case 'gray1'         % range = [0:+1] ; colormap gray
    colors.mode = 'gray1' ;
    colors.zero = 2 ;    % black
    colors.span = 62 ;   % max = 2+62 = 64 = white
    colors.canv = 1 ;    % light blue -- see below
    colors.map  = gray(64) ; % COLORMAP(gray)
    colors.map(colors.canv,:) = [0,0.7,1] ;  % [0,0,0.9]?
  case 'gray2'         % range = [-1:+1] ; colormap gray
    colors.mode = 'gray2' ;
    colors.zero = 33 ;   % gray
    colors.span = 31 ;   % max = 31+33 = 64 = white
    colors.canv = 1 ;    % light blue
    colors.map  = gray(64) ; % COLORMAP(gray)
    colors.map(colors.canv,:) = [0,0.7,1] ;  % [0,0,0.9]?
  case 'frame'           % range = [0:+1] ; colormap(flipud(gray))
    colors.mode = 'frame' ;
    colors.zero = 1 ;    % white
    colors.span = 63 ;   % max = 1+63 = 64 = black
    colors.canv = 1 ;    % white
    colors.frame= 64 ;   % black frame around each data element
    colors.map  = flipud(gray(64)) ;  % 1=white, 64=black
  case 'fill'            % B/W fill  diagram w/ 24 levels
    colors.mode = 'fill' ;
    colors.zero = 1 ;    % fill at least 1 pixel no matter what
    colors.fill = prod(elt_sz) ;   % black=25  for 5x5 data elements
    colors.span = colors.fill - colors.zero ;  % 24 levels
    colors.canv = 1 ;              % white
    colors.map  = flipud(gray(prod(elt_sz))) ; % 1=white, 25=black
    colors.colorbar = 'off' ;
  otherwise
     error(['Use one of ''hot1'', ''jet1'', ''coldhot2'',' ...
            ' ''gray1'', ''gray2'', ''frame'' or ''fill''.']) ;
  end
end
colors.ordinate = 0 ;           % no vertical line  (it appears too thick)
if (~isfield(colors,'colorbar'))
   colors.colorbar = 'vert' ;   % vertical colorbar by default
end

if (isstruct(spec))    % seed params
  %- Read as many 'root' fields as supplied
  if (~isfield(spec,'D_orient')) D_orient = spec.D_orient(:)' ; end
  if (~isfield(spec,'D_radii'))  D_radii  = spec.D_radii(:)'  ; end
  if (~isfield(spec,'elt_sz'))   elt_sz  = spec.elt_sz ;  end
  if (~isfield(spec,'canv_sz'))  canv_sz = spec.canv_sz ; end
  if (~isfield(spec,'colors'))   colors  = spec.colors ;  end
elseif (~ischar(spec))
  error('SPEC must be either a ''seed'' structure or a string.') ;
end

%--- Size of the representation (or weight) matrix
N_rays  = length(D_orient) ;
N_rings = length(D_radii) ;
rep_sz = [N_rays,N_rings] ;    % [N_orient,N_spfreq]

%--- Positions of the rectangular 'elements'
TH = (90-D_orient) .* (pi/180) ;   % radians clockwise from vertical
TH = repmat(TH',1,N_rings) ;
R = repmat(D_radii,N_rays,1) ;

[X,Y] = pol2cart(TH(:),R(:)) ;     % polar --> cartesian coordinates
X = round(X) ; Y = round(Y) ;      % list of 'elements' on a grid
%plot(Hparams.X,Hparams.Y,'o') ; axis xy ;

%--- Canvas size
X = X-min(X)+1 ; Y = Y-min(Y)+1 ;  % minX = minY = 1
maxX = max(X) + elt_sz(2)-1 ;
maxY = max(Y) + elt_sz(1)-1 ;

canv_sz = max(canv_sz,[2+maxY+2,2+maxX+2]) ;
marginX = floor((canv_sz(2)-maxX)/2) ;
marginY = floor((canv_sz(1)-maxY)/2) ;

%--- Pixel offsets relative to the south-west corner of each 'element'
footX = repmat([1:elt_sz(2)],elt_sz(1),1) ;
footY = repmat([1:elt_sz(1)]',1,elt_sz(2)) ;
offsets = sub2ind(canv_sz,footY(:)',footX(:)')-1 ;
N_pix = length(offsets) ;

%--- Mapping indices
idxSW = sub2ind(canv_sz,Y+marginY,X+marginX) ;  % south-west corners
mapping = repmat(idxSW,1,N_pix) + repmat(offsets,length(idxSW),1) ;

%--- Filling order
if (prod(elt_sz)==25)
   order = [ 2  1  5 10 17 ; ...
             3  4  6 11 18 ; ...
             7  8  9 12 19 ; ...
            13 14 15 16 20 ; ...
            21 22 23 24 25       ] ;
   [foo,idx] = sort(order(:)) ;
   mapping = mapping(:,idx) ;   
%else leave MATLAB's columwise order as default for nonstandard ELT_SZ'esa
end

%--- Frame indices
if (isfield(colors,'frame'))          % framing requested?
  fr = zeros(canv_sz) ;
  fr(1,1:elt_sz(2)+2) = 1 ;             % top
  fr(elt_sz(1)+2,1:elt_sz(2)+2) = 1 ;   % bottom
  fr(1:elt_sz(1)+2,1) = 1 ;             % left
  fr(1:elt_sz(1)+2,elt_sz(2)+2) = 1 ;   % right
  frame_idx = find(fr==1)' ;                      % relative to (1,1)
  frame_idx = frame_idx - sub2ind(canv_sz,2,2) ;  % relative to (0,0)
  N_fr = length(frame_idx) ;
  frame = repmat(idxSW,1,N_fr) + repmat(frame_idx,length(idxSW),1) ;
end

%canvas = zeros(canv_sz) ;
%canvas(idxSW) = 1 ; canvas(idxSW(1)+offsets) = 0.5 ;   OR
%canvas(mapping(:)) = 1 ;
%imagesc(canvas) ; axis image xy ;

%--- Axis ticks and labels
axis.xtick = X(1:N_rays)' + elt_sz(2)-1 ;  % Xs of the bottom ring
axis.xticklabel = XTickLabel ;
y = reshape(Y,N_rays,N_rings) ;
axis.ytick = y(1,:) + elt_sz(1)-1 ;        % Ys of the leftmost ray
axis.yticklabel = YTickLabel ;

%--- Pack and return
Hparams.rep_sz = rep_sz ;
Hparams.elt_sz = elt_sz ;
Hparams.canv_sz = canv_sz ;
Hparams.D_orient = D_orient ;
Hparams.D_radii  = D_radii ;
Hparams.colors = colors ;
Hparams.axis = axis ;
Hparams.mapping = mapping ;
if (isfield(colors,'frame'))  Hparams.frame = frame ;  end

%--- Return HPARAMS
%%%%% End of file HINTON_PARAMS.M
