function [clipped_image] = imclip(original_photo, lo, hi, levels)
% clipped_image = imclip(original_photo, hi, lo, levels)
% stretches the photo
% so that points equal to lo become black (0),
% while points equal to (hi-1) become white(levels-1).
% Then clips the image to that range 0...(levels-1).
%
% Usage:
%   cameraman = double(imread('cameraman.tif'));
%   % threshold at 127.5
%   A = imclip(cameraman, 127, 129);
%   figure; colormap(gray(256));
%   image(double(A)+1);
%   % stretch to see pocket better:
%   A = imclip(cameraman, 5, 30);
%   figure; colormap(gray(256));
%   image(double(A)+1);
%
% 2's complement saturation logic:
% if you want to convert 
% integers in the range -4...+3
% to integers in the range 0...+7,
% use
%   A = imclip(x, -4, 4, 8);
%
% "levels" defaults to 256,
% "lo" defaults to 0, and
% "hi" defaults to 256. This way
% t = imclip(original_photo);
% returns exactly the same image,
% but with pixels less than 0 set to 0,
% and pixels greater than 255 set to 255.
%
% See also STRETCH, IMAGESC, D2S, SIGNED_CHAR_TO_DOUBLE.

% Change log:
% 1999-07-09:DAV: fixed so using hi < lo does inversion properly.
% 1999-07-08:DAV: David Cary <d.cary at ieee.org> started.

if(nargin < 4),
    levels = 256; % default number of gray levels
end;

if(nargin < 3),
   hi = 256; % default hi level
end;

if(nargin < 2),
    lo = 0; % default lo level
end;

% lo = 0, hi = 256, levels = 256
% should stretch from 0 ... 255.
input_levels = (hi-1) - lo;

temp_photo = original_photo - lo;
scale = (levels-1)/(input_levels);
clipped_image = temp_photo .* scale;

I = find( clipped_image < 0 );
clipped_image(I) = 0;
I = find( (levels-1) < clipped_image );
clipped_image(I) = levels-1;

% end imclip.m