% @(#)definehoug.hlq	19.1 (ESO-IPG) 02/25/03 14:18:32
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      definehoug.hlq
%.AUTHOR     JDP, IPG/ESO
%.KEYWORDS   MIDAS, help files, DEFINE/HOUGH
%.PURPOSE    On-line help file for the command: DEFINE/HOUGH
%.VERSION    1.0  29-JUL-1991 : Creation, PB
%----------------------------------------------------------------
\se
SECTION./HOUGH
\es\co
DEFINE/HOUGH					   7-DEC-1994  PB
\oc\su
DEFINE/HOUGH  [ordref] [nbord] [hwid] [hough_par] [thresh] [degx,degy] 
              [hot_thres,step] [hough_setup]
	define echelle order positions; automatic detection by Hough transform.
\us\pu
Purpose:    
            Search for order positions in a 2-D echelle frame. The positions 
            of points located in order and in interorder space are stored 
            in an auxiliary table, named order.tbl
\up\sy
Syntax:     
            DEFINE/HOUGH [ordref] [nbord] [hwid] [hough_par] [thresh] 
                         [degx,degy] [hot_thres,step] [hough_setup]
\ys\pa
            ordref = raw flat field used as input image. \\
                     Echelle keyword is ORDREF.  
\ap\pa
            nbord  = number of order to be detected. \\
                     If nbord is set to 0, the number of orders is 
                     estimated automatically. \\
                     If nbord<0, the procedure will detect abs(nbord)
                     orders, then prompt for a differential number of
                     orders (e.g. +3 for 3 more orders, -1 for one less),
                     until the user enters 0 to finish the procedure. \\
                     Echelle keyword is NBORDI. Default value is 0.
\ap\pa
            hwid   = half-width of the orders in pixel.
                     If hwid is set to 0, the half-width is measured for
                     each order.\\
                     Echelle keyword is WIDTHI. Default value is 0.
\ap\pa
            hough_par =  Possible values are DENSE, CENTER, ALL, NO, FOLLOW,
                         or Step,Nb-trace. Default is DENSE. No echelle
                         keyword controls this parameter. If it is 
                         preceded by a minus sign (e.g. -CENTER), no
                         median filter is applied to the frame.

                     DENSE generate a Hough transform based on 50 columns
                           evenly distributed on the frame.

                     CENTER generate a Hough transform based on 50 columns
                           covering 25\% of the frame width in its central
                           part.

                     ALL   generate a full Hough transform of the frame.

                     step,nb-trace generate a Hough transform based on 
                           (nb-trace) columns separated by (step) pixels
                           around the central column.

                     NO    skips the Hough transform and take frame 
                           middummh.bdf as the hough transform. \&h is created
                           by a previous DEFINE/ECHELLE with option\\
                           hough-par = DENSE,ALL or Step,nb-tr.

                     FOLLOW skips the Hough transform and order detection
                           and performs only order following and bivariate
                           fitting.
\ap\pa
            thresh = threshold for order segmentation when performing
                     the order following. If thresh is set to 0., an
                     optimal threshold is defined for each order.
                     Echelle keyword is THRESI. Default value is 0.
                     A threshold can be defined for each order independently
                     in the column :THRES of the temporary table middummr.tbl.
                     This table is created by a preliminary execution of 
                     define/hough. After edition of the thresholds, restart
                     with the option DEFINE/HOUGH P4=FOLLOW.
\ap\pa
            degx,degy = degree of the 2D polynomial used to approximate the
                     position of the orders as y = f(x,m), where\\
                         y: is the line number in pixels;\\
                         x: is the sample number in pixels;\\
                         m: a relative order number.\\
                     Echelle keyword is DEFPOL. Default is 3,4
\ap\pa
            hot_thres,step = Hot threshold for the rejection of bright
                     features (particle hits, hot pixels). Default is
                     100 000. Step for measuring orders positions when
                     performing the order following. Default is 10.\\
                     No echelle keyword controls this parameter.
\ap\pa
            hough_setup = This parameter is transfered as parameter P8
                     to the command HOUGH/ECHELLE. It enables to set the
                     boundaries (slope limits, step) of the transformed
                     space. See HOUGH/ECHELLE for more details.
\ap\no
Note:       
            1) The auxiliary table order.tbl is used as intermediate storage
            Parameters can be defaulted to the corresponding session
            values (SHOW/ECHELLE to display the current values).
 \\
            2) The results will be more accurate if the keyword SCAN has 
            been correctly set (see SCAN/ECHELLE).
  \\
            3) The algorithm involves four main steps:\\
                    1) Median filtering \\
                    2) Hough transform\\
                    3) Order detection\\
                    4) Order following\\
            Step  1 is skipped by using a minus sign (e.g. hough-par=-DENSE)\\
            Steps 1 and 2 are skipped if hough-par=NO\\
            Steps 1,2,3 are skipped if hough-par=FOLLOW
 \\
            4) In case of emergency:
 \\
            Always start with the default values (especially 
            SCAN=0,0, hough-par=DENSE, NBORDI=WIDTHI=WIDTHI=0) and 
            depending on the result, consider the following:
 \\
            A cause of problems in the order detection can be
            the presence of particle hits or defaults not removed by the
            median filtering. Check the intermediate image middummi.bdf.
            If necessary, filter the order reference frame and restart
            with DEFINE/HOUGH P4=-DENSE or P4=-CENTER.
 \\
            The width of the orders, especially for wide orders,
            could be wrongly estimated. The width as estimated by the
            automatic program is displayed during order detection in a
            line like: \\
            Detect. order N, slope xxx, interc. yyy, fwhm zzz \\
            The real width of the orders can be measured with a 
            command like GET/CURSOR and the session keyword WIDTHI
            set to this value.
 \\
            If the orders present a strong curvature, the method
            hough-par=CENTER can be more appropriate than the default
            hough-par=DENSE.
 \\
            Some defaults are sometimes located at the top or the bottom part
            of the spectrum (saturated rows, truncatured orders). To avoid
            them, update the keyword SCAN with the command SCAN/ECHELLE
            and restart with DEFINE/HOUGH.
 \\
            Problems can be also due to the detection of an order badly
            defined, like a truncated order, which cannot be properly detected.
            When the procedure performs the cluster detection, check
            whether the slope and fwhm vary regularly. Orders are detected
            by order of brightness, so the intercept is not supposed
            to vary monotonously. If the last orders present weird
            parameters, it is possible to enforce the number of detected 
            order with the command SET/ECH NBORDI=<number> and restart.
            If an order is wrongly detected in the middle of the cluster
            detection (intermediate brightness) and if this order is 
            located in the middle of the spectrum, it wil be necessary to
            edit the order detection table middummr.tbl.
 \\
            Before the step of order following, it is possible to
            edit the table middummr.tbl to correct the order detection.
            After a first run of DEFINE/HOUGH, check the slope, intercept,
            width and order number of the different orders. Restart with
            DEFINE/HOUGH P4=FOLLOW. If some problem occurs in the order
            following due to the automatic estimate of threshold, edit
            the table \&r and update the threshold (see above parameter
            thresh). Restart with DEFINE/HOUGH P4=FOLLOW.
 \\
            5) A description of the method  is available in      
            Ballester, 1994, Astron. Astrophys. 286, pp. 1011-1018

\on\exs
Examples:
\ex
            DEFI/HOUGH stdfr   
            For automatic process
\xe\ex
            DEFI/HOUGH stdfr  12          
            Enforces the detection of 12 orders
\xe\ex
            DEFI/HOUGH  stdfr 12 ? F 100. 
            To redo order following (thresh=100)
\xe \sxe







