proj/mag/ident/libs/mexfunctions/Doc/mrf_segment_wts_docstring.h

/*
 * This file is generated by a script, do not edit.
 *
 * This documentation string was generated from
 * a C comment block within a mex program
 * by `doc2docstring.py' on Wed Jul 14 12:49:32 2010.
 */
 
static const char docstring[] =
    "mrf_segment_wts: segment with a discrete Markov random field\n"
    "\n"
    " [yp,post] = mrf_segment_wts(iter,T,beta,alpha,dist,y,lprob1,...,lprobK)\n"
    " * Performs iter full sweeps (using temperature schedule T) of\n"
    " Gibbs sampling on an input labeling y, with entries in 1..K, to produce\n"
    " an output labeling yp.  Posterior probability is optionally returned.\n"
    " Posterior is actually an energy function, which is correct with respect\n"
    " to changes in y, but does not have the correct scale factors which\n"
    " vary with beta, alpha, and dist.\n"
    " * Conditional distributions of pixel data x given class y are\n"
    " calculated externally, and given by lprob1...lprobK, as log-\n"
    " probabilities.\n"
    " * Per-class biases are given by alpha, which can be empty, indicating\n"
    " no bias.  Otherwise, the interpretation is alpha(k) is the prior\n"
    " log-probability of seeing class k.\n"
    " * The smoothness parameter of the MRF (Potts model) is beta.  If beta\n"
    " is a matrix, beta(k,l) is the smoothness \"reward\" given to a site of\n"
    " class k for having a neighbor of class l.  The scalar beta thus\n"
    " corresponds to a diagonal matrix with repeated beta entries.\n"
    " (beta and alpha agree with definitions in the Besag paper below.)\n"
    " * Pixel-pixel distances are given by dist, where dist(nu,m,n) gives\n"
    " the distance between pixel (i,j) and its neighbor number nu, looking\n"
    " up or left.  For the 3x3 neighborhood, pixel s=(m,n) has 8 neighbors s',\n"
    " and distances to 4 of them, where s'<s, at offsets:\n"
    "   (-1,-1),(0,-1),(1,-1),(-1,0),\n"
    " are given in that order, in dist(i,j,:).  The other neighbors\n"
    " have s'>s, and the corresponding distances are listed in the\n"
    " symmetric entries of dist.  If dist=[], it is taken to be\n"
    " everywhere 1, thus removing the direction-sensitive smoothing\n"
    " (but still smoothing).\n"
    " * Classes are 1..K, but labels NaN and 0 are not updated or counted\n"
    " as neighbors.  Any NaN in a log-probability forces a NaN in the\n"
    " output class.\n"
    " * A `clock' at each pixel may speed computation.  This recognizes that,\n"
    " if the neighbors of a pixel do not change, the Gibbs sampler is rolling\n"
    " a stationary die once per iteration to determine the pixel label.\n"
    " The waiting time until another label change is then geometric,\n"
    " and this waiting time can be sampled once to short-circuit a series\n"
    " of die rolls.  See Ripley, below.\n"
    " * The speedup of this method is greatest when few labels change.  If\n"
    " supplied, iter(2) is the threshold (in [0,1]) of #changed/#labels\n"
    " for a switchover from the ordinary method to the clock method.\n"
    " (Only one switch is permitted in the iteration sequence.)\n"
    " If iter(2) = 0, the ordinary coin-flip method is used throughout;\n"
    " if =1, the clock method is used throughout.\n"
    " * Annealing is permitted through the `temperature' parameter T.\n"
    " Initial temperature is T(1), reduced by a factor of T(2) at each\n"
    " iteration. The default T(2) = 1 suppresses annealing.\n"
    " Clocks are reset whenever the cumulative drop in temperature\n"
    " reaches a factor of T(3).  (Roughly, then, clocks are reset every\n"
    " log(T(3))/log(T(2)) iterations.)  If T(4) is present and equals\n"
    " zero, additional iterations are done at zero temperature, at the\n"
    " end of the normal annealing schedule, until the labels reach a\n"
    " fixed point.  (This is equivalent to Besag's ICM.)\n"
    " * If iter[1] has a fractional part, that part is multiplied by 2**31\n"
    " and rounded to set the desired random number seed; if not, a\n"
    " pseudorandom seed is generated.  This is provided to allow repeatability.\n"
    " * This is implemented as a MEX file.\n"
    "\n"
    " Inputs:\n"
    "   int iter[1] or [2] = [0 0.05];\n"
    "   real T[0] or [1] or [2] or [3] or [4] = [1 1 0.8 0];\n"
    "   real beta[1] or [K,K];\n"
    "   real alpha[K] or [0] = [];\n"
    "   real dist[nbr,m,n] or [0];\n"
    "   int y[m,n];  -- 1 <= y <= K, or 0 or NaN\n"
    "   real lprob1[m,n];\n"
    "   ...\n"
    "   real lprobK[m,n];\n"
    "\n"
    " Outputs:\n"
    "   int yp[m,n];  -- 1 <= y <= K, or 0 or NaN\n"
    "   opt real post;\n"
    "\n"
    " See Also:  mrf_segment, makemrfdiscwts\n"
    " Geman and Geman, Stochastic relaxation, Gibbs distributions, and\n"
    " the Bayesian restoration of images, IEEE PAMI Nov. 1984\n"
    " J. Besag, On the statistical analysis of dirty pictures, JRSSB, 1986\n"
    " B. D. Ripley, Statistical Inference for Spatial Processes,\n"
    " Cambridge U., 1988, p. 99\n"
    "\n"
    " turmon sep/oct 2006, weighted distance\n"
    " turmon 5 march 1999, modified to streamline for batch operations\n"
    " MJT 18 Mar 1996\n"
    "\n"
    "";

/* End of generated file */

---