carpet(x1, x2, y, offset, nref, linspec1, linspec2, varargin)

function h = carpet(x1, x2, y, offset, nref, linspec1, linspec2, varargin)
%CARPET Plots a carpet plot with two independent and one dependent variable.
%   h = carpet(x1, x2, y, offset) generates a carpet plot with
%   independent variables x1 & x2 and dependent variable y.  The plot is
%   created using a cheater axis generated by the equation:
%
%   xcheat = x1 + x2 * offset.
%
%   x1 & x2 may be vectors, or they may be matrices as generated by
%   MESHGRID.  x1, x2, & y should be arranged such that they could be
%   plotted with SURF(x1,x2,y).
%
%   Handles to the resulting carpet plot curves are returned in h.
%
%   Setting nonzero nref will cause lines in the carpet plot to be skipped.
%   This can be used to create smooth curves in the carpet plot without
%   excess clutter.  Default nref = 0.  The same value of nref is applied
%   to both x1 and x2 directions.  Refined vectors can be created using
%   REFVEC.
%
%   linspec1 specifies the line style for the x1=constant lines.  If it is
%   not specified, it defaults to 'k'.
%
%   linspec2 specifies the line style for the x2=constant lines.  If it is
%   not specified, it defaults to linspec1.
%
%   Any additional arguments passed to CARPET are passed to the plot
%   command.
%
%   See also CARPETCONVERT, CARPETCONTOURCONVERT, REFVEC.

%   Rob McDonald 
%   [e-mail]  
%   19 February 2013 v. 1.0

if( nargin < 5 )
  nref = 0;
end

% Handle default line styles.
if( nargin < 6 )
  linspec1 = 'k';
end

if( nargin < 7 )
  linspec2 = linspec1;
end

% If input is not matrix similar to meshgrid, make it so.
if( isvector(x1) && isvector(x2) )
  [X1,X2] = meshgrid( x1, x2 );
else
  X1 = x1;
  X2 = x2;
end

% Calculate the cheater axis.
Xcheat = X1 + X2 * offset;

% Plot the carpet plot lines.
h = plot(Xcheat(1:nref+1:end,:)', y(1:nref+1:end,:)', linspec1,...
         Xcheat(:,1:nref+1:end), y(:,1:nref+1:end), linspec2, varargin{:});

% Hide the X-axis and turn off the box.
ca = gca;
set(ca,'XTick',[])
box off
set(ca,'XColor',[1,1,1])