% LOGISTICWEIGHTING  Weighting function based on the logistics function
% 
% Adaptation of the generalised logistics function for defining the variation of
% a weighting function for blending images (among other things).
% The function computes a form of the generalised logistics function with
% asymptotes -A and +A, and growth rate b.
%
%    W(x)  = A - 2*A/(1 + e^(-b*x))
%
% Usage: W = logisticweighting(x, b, R)
% 
% Arguments: x - Value, or array of values at which to evaluate the weighting
%                function.
%            b - Parameter specifying the growth rate of the logistics function.
%                This controls the slope of the weighting function at its
%                midpoint.  Probably most convenient to specify this as a
%                power of 2.
%                b = 0      Perfect linear transition from wmin to wmax. 
%                b = 2^0    Near linear transition from wmin to wmax.
%                b = 2^4    Sigmoidal transition.
%                b = 2^10   Near step-like transition at midpoint.
%            R - 4-vector specifying [xmin, xmax, wmin, wmax] the minimum and
%                maximum weights over the minimum and maximum x values that
%                will be used.   The midpoint of the sigmoidal weighting
%                function will occur at (xmin+xmax)/2 at a value of
%                (wmin+wmax)/2. Note that if an x value outside of this range
%                is supplied the resulting weight will also be outside of the
%                desired range. Defaults to  R = [-1 1 -1 1]
%
% Returns:   W - Weight values for each supplied x-coordinate.
%

% Copyright (c) 2012 Peter Kovesi
% Centre for Exploration Targeting
% The University of Western Australia
% peter.kovesi at uwa edu au
% 
% Permission is hereby granted, free of charge, to any person obtaining a copy
% of this software and associated documentation files (the "Software"), to deal
% in the Software without restriction, subject to the following conditions:
% 
% The above copyright notice and this permission notice shall be included in 
% all copies or substantial portions of the Software.
%
% The Software is provided "as is", without warranty of any kind.
%
% May 2012

function w = logisticweighting(x, b, R)
    
    if ~exist('R', 'var'), R = [-1 1 -1 1]; end
    
    b = max(b, 1e-10);  % Constrain b to a small value that does not cause
                        % numerical problems
    
    [xmin xmax wmin wmax] = deal(R(1), R(2), R(3), R(4));
    xHalfRange = (xmax-xmin)/2;
    wHalfRange = (wmax-wmin)/2;
    M = (xmin+xmax)/2; % Midpoint of curve

    % We use a form of the generalised logistics function with asymptotes -A and
    % +A, and growth rate b.
    %
    % W(x)  = A - 2*A/(1 + e^(-b*x))
    %
    % First, given the desired value of b, we solve for the value of A that will
    % generate a generalised logistics curve centred on (0,0) and passing
    % through (-xrange/2, -wrange/2) and (+xrange/2, +wrange/2)
    A = wHalfRange/(1 - 2/(1+exp(-b*xHalfRange)));
    
    % Apply an offset of M to x to shift the curve to the desired position
    % and add a vertical offset to obtain the desired weighting range
    w = A - 2*A./(1 + exp(-b*(x-M))) + (wmin+wHalfRange);