section of routines in detect.i

functions in detect.i -

find_1d_minmax


             find_1d_minmax(a)  
 
      -or- find_1d_minmax(a, what)  
    Find local minima/maxima in 1-D array  A.  If WHAT is nil or zero, the  
    function returns an array of integers  with same shape as A and set to  
    +1 where A is a local maximum, to -1 where A is a local minimum and to  
    0  elsewhere.  Otherwise, the  function returns  the indices  of local  
    maxima or local minima depending  whether WHAT is positive or negative  
    (the result may be empty).  WHAT may also be a string: "any", "min" or  
    "max".  
    
    Contiguous extrema,  say a  local maximum LOCMAX  and a  local minimum  
    LOCMIN, are separated by a strict hysteresis (or a gap) such that:  
    
       LOCMAX - LOCMIN > HYSTERESIS*(max(A) - min(A)) >= 0  
    
    The default  is HYSTERESIS=0, i.e. all strict  local minima/maxima are  
    detected.  However,  in order  to avoid being  too sensitive  to local  
    extrema  (for  instance  because  of  noise), the  hysteresis  of  the  
    algorithm  can  be  adjusted  by  keywords INF,  SUP,  ALEV,  RLEV  or  
    HYSTERESIS.   Note  that  the   easiest  keywords  to  play  with  are  
    HYSTERESIS or ATOL and RTOL (SUP and INF are more tricky to use).  
    
    HYSTERESIS = level of hysteresis  relative to peak-to-peak value of A.  
          HYSTERESIS   must   be  conformable   with   A  and   everywhere  
          non-negative (this  is not checked).  HYSTERESIS  is another way  
          to  specify the absolute  tolerance and  is only  significant if  
          ALEV is not specified.   Specifying HYSTERESIS gives an absolute  
          tolerance:  
             ALEV = (max(A) - min(A))*HYSTERESIS.  
          Hence the lower  is the hysteresis, the more  local extrema will  
          be  detected.   As  a  rule  of  thumb, a  good  value  for  the  
          hysteresis is the 3-4 divided by the signal-to-noise-ratio.  
    
    ALEV = absolute level of  hysteresis.  ALEV must be conformable with A  
          and such that  ALEV >= 0 everywhere (this  is not checked).  The  
          default is  the same as with ALEV=0  (unless  keyword HYSTERESIS  
          is specified).  
    
    RLEV = relative level of hysteresis.  RLEV must be conformable with A  
          and such  that 0 <= RLEV  < 1 everywhere (this  is not checked).  
          The default is the same as with RLEV=0.  
    
    INF = inferior  bound with respect to  a maximum: A(i) may  be a local  
          maximum with respect to A(j) if  and only if A(j) < INF(i).  INF  
          must  have the  same number  of elements  as A.   If INF  is not  
          specified,  it is  computed from  the  value of  ALEV and  RLEV.  
          Given ALEV and RLEV, the inferior bound is:  
              INF = A - (ALEV + RLEV*abs(A))  
    
    SUP = superior  bound with respect to  a minimum: A(i) may  be a local  
          minimum with respect to A(j) if  and only if A(j) > SUP(i).  SUP  
          must  have the  same number  of elements  as A.   If SUP  is not  
          specified,  it is  computed from  the  value of  ALEV and  RLEV.  
          Given ALEV and RLEV, the superior bound is such that:  
              A = SUP - (ALEV + RLEV*abs(SUP))  
          or:  
              SUP = (A + ALEV)/(1 - sign(SUP)*RLEV)  
          since 0 <= RLEV < 1  then SUP has the same  sign as A + ALEV and  
          finally:  
              SUP = (A + ALEV)/(1 - sign(A + ALEV)*RLEV)

SEE ALSO:

plot_1d_minmax

find_2d_max


             map = find_2d_max(img)  
 
     Find disjoint  local maxima in  2-D array IMG  and return an  array of  
     integers MAP with same shape as IMG and set as follow:  
         MAP(x,y) = -1       for bad pixels (or strictly above CMAX)  
         MAP(x,y) =  0       for pixels not assigned to any local maximum  
         MAP(x,y) =  N (N>0) for pixels assigned to N-th local maximum  
     The  maxima  are  labelled  from   the  higher  to  the  lower.  Hence  
     where(MAP==1) gives the indices of pixels around the stronger maximum.  
     The selection  works as follows.   The algorithm starts with  the next  
     (unassigned) higher maximum and  then marks all connected pixels which  
     are greater or equal to a given  threshold.  If a bad pixel or a pixel  
     already assigned to another  maximum is encountered during this stage,  
     the algorithm  gives up this maximum  and proceeds with  the next one.  
     Otherwise,  the marked  region  is  assigned to  the  maximum and  the  
     algorithm proceeds with the  next one.  This algorithm guarantees that  
     the marked regions are all separated (by at least one pixel) from each  
     other and from any bad pixel.  The threshold reads:  
         THRESHOLD = PEAK - RLEV*abs(PEAK) - ALEV  
     where PEAK is the current  maximum, ALEV (ALEV>=0 everywhere) and RLEV  
     (0<=RLEV<1 everywhere) are the absolute and relative threshold levels.  
     ALEV and RLEV are given by keyword. By default, ALEV=0 and RLEV=0.  
       
     Keyword CMIN can be used to  set the minimum value of a local maximum.  
     Since searching all  maxima may be prohibitively long,  it is strongly  
     recommended to limit the depth of the search by the keyword CMIN.  
     Keywords BAD  and/or CMAX can be used  to mark as bad  pixels the ones  
     for which BAD is non-zero and/or which are (strictly) above CMAX.  
     If  specified, keywords ALEV,  RLEV, CMIN,  CMAX and  BAD must  all be  
     conformable with  IMG; you can  therefore setup things on  a per-pixel  
     basis, or columnwise, or rowwise...  
       
  EXAMPLE:    
     For instance, if SIGMA is the standard deviation of noise in the image  
     and  BACKGROUND is  its background  level (both  could  be pixelwise),  
     then:  
         find_2d_max(IMG, cmin=BACKGROUND+3*SIGMA, alev=4*SIGMA)  
     will find all the maxima in  IMG which are above the background with a  
     3 SIGMA  confidence level  and mark the  regions around  every maximum  
     (with value PEAK) where connected pixels are such that:  
         IMG >= PEAK - 4*SIGMA  
   HINTS:  
     1. Use  keyword CMIN  to limit  the  search (possibly  on a  per-pixel  
        basis).  
     2. The search  necessitates to sort  the pixels elligible to  be local  
        maxima (all which are above CMIN,  below CMAX and not in BAD), this  
        sorting can be very long for large images (again use CMIN) but also  
        for integer valued images  (a drawback of the quicksort algorithm?)  
        to overcome this  it is sufficient to add a  small amount of random  
        noise in the image, for instance:  
            find_2d_max(IMG + 1e-9*(random(dimsof(IMG)) - 0.5), ...)  
        but beware that this can make the result (slightly) inpredictible.