function p=vis_patch(lattice)

%VIS_PATCH Defines the basic patches used in som_plane
%
% p=vis_patch(lattice)
%
% INPUT ARGUMENTS ([]'s are optional)
%
%  lattice   (string) 'rect', 'hexa' or 'hexagon'
%
% OUTPUT ARGUMENTS   
%
%  p (matrix) Lx2 matrix defining the verticess of the patch
%
% This function produces vertex coordinates for a patch presenting
% a map unit in hexagonal or rectangular lattice with its centre in (0,0). 
%
% For more help, try 'type vis_patch' or check out the helpdesk.

%%%% DETAILED DESCRIPTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% vis_patch
%
% SYNTAX
%  
% p=vis_patch(lattice)
% 
% PURPOSE
% 
% Mainly a subroutine of som_cplane
% 
% DESCRIPTON 
%
% Forms a prototype of a map unit patch for som_cplane function
%
% REQUIRED INPUT ARGUMENTS
%
% lattice (string)
%
% Possible values are
%
% 'hexa'
% 
%  produces vertex coordiantes for a hexagoanl patch which 
%  has its center on (0,0), unit width, and a height of 1.3334 units.
%  This is not a regular  hexagon but such that the node which has 
%  topological coordinates (a,b) has its center in the visualization 
%  at coordinates (a,b) for odd a and at (a,b+.5) for even a. 
%  The non-regular look of the patch is taken care simply 
%  by changing the axis ratio.
%
% 'rect'
%
%  produces vertex coordinates for a uniform rectangular patch.
%  having its center on (0,0) and unit sidelength. Used as a subfunction in 
%  som_cplane.
%
% 'hexagon'
%
%  produces vertex coordinates for a regular hexagonal patch.
%  It may be used in som_cplane if, for some reason, truly regular hexagons 
%  are needed instead of the default unit markers which are not
%  uniform, but have integer y-coordinates in the lattice.
%
% OUTPUT ARGUMENTS
%
% p (matrix)
%
% Values are
%
%   case 'rect'        case 'hexa'                case 'hexagon'
%    p=[[-.5 -.5];...     p=[[0     0.6667];...    p=[[0     0.5774];...
%       [-.5  .5];...        [0.5   0.3333];...       [0.5   0.2887];...
%       [ .5  .5];...        [0.5  -0.3333];...       [0.5  -0.2887];...
%       [ .5 -.5]];          [0    -0.6667];...       [0    -0.5774];...
%                            [-0.5 -0.3333];...       [-0.5 -0.2887];...
%                            [-0.5  0.3333]];         [-0.5  0.2887]]; 
%
% EXAMPLES
%
%  som_cplane(vis_patch('rect'),[6 5],'none');
%   % this produces the same result as som_cplane('rect',[6 5], 'none')
%  
%  som_cplane(vis_patch('hexa'), vis_unit_coord('hexa',[6 5]), 'none');
%   % produces in principle the same result as 
%   % som_cplane(vis_patch('hexa'),[6 5],'none'), 
%   % _but_ in this case the axis are not rescaled and the non-regular 
%   % shape of hexagons can be seen.
%
%  som_cplane(vis_patch('hexagon'), som_unit_coords([6 5],'hexa'), 'none');
%   % produces a truly regular hexa lattice 
%
% SEE ALSO 
%
%  VIS_UNIT_COORD The default 'hexa' and 'rect' coordinates in visualizations
%  SOM_UNIT_COORDS Locations of units on the SOM grid

% Version 0.5gamma Johan 041099
% Copyright (c) 1999 by the SOM toolbox programming team.
% http://www.cis.hut.fi/projects/somtoolbox/             

if ~ischar(lattice)
  error('Input argument should be a string')
else
  switch lattice
  case 'rect'
    p=[[-.5 -.5]; ...
      [-.5 .5];...
      [.5 .5];...
      [.5 -.5]];
  case 'hexagon'
    p=[[0 0.5774];...
      [0.5 0.2887];...
      [0.5 -0.2887];...
      [0 -0.5774];...
      [-0.5 -0.2887];...
      [-0.5 0.2887]];
  case 'hexa'
    p=[[0 0.6667];...
      [0.5 0.3333];...
      [0.5 -0.3333];...
      [0 -0.6667];...
      [-0.5 -0.3333];...
      [-0.5 0.3333]];
  otherwise
    error('Unknown lattice');
  end
end


