
                     ================================
                    |        __   __   _   _         |
                    |        \ \ / /__| |_(_)        |
                    |         \ V / _ \ __| |        |
                    |          | |  __/ |_| |        |
                    |          |_|\___|\__|_|        |
                    |                                |
                    |    -- a Yorick extension --    |
                    |                                |
                    |   (2002-2005) Eric Thibaut    |
                    |                                |
                     ================================


DESCRIPTION
-----------

  Yeti is an extension of Yorick (a fast interpreted interactive data
  processing language written by David Munro) which implements (see QUICK
  REFERENCE below for a list of additional functions):

   * hash table objects
   * regular expressions
   * complex, real-complex and complex-real FFT by FFTW (the Fastest Fourier
     Transform in the West - version 2)
   * wavelet filtering (" trou" method)
   * fast convolution along a chosen dimension with various border conditions
   * more string functions
   * memory hacking routines
   * more math functions (sinc, round, arc)
   * generalized matrix-vector multiplication (with possibly sparse matrix)
   * routines to query/check Yorick's symbols
   * support for reading TIFF images
   * morpho-math operators
   * 120 special functions from GSL (the GNU Scientific Library)
   * ...

  This distribution of Yeti may come with several extensions (depending
  whether corresponding directories exist or not):

   * yeti_fftw - support for FFTW
   * yeti_gsl - implements special functions from GSL
   * yeti_regex - support for POSIX regular expressions
   * yeti_tiff - support for reading TIFF images



COMPILATION AND INSTALLATION OF YETI SOFTWARE SUITE
---------------------------------------------------

  Starting with version 6.0.0, Yeti is built as a regular Yorick
  plugin and some of the Yeti extensions are built as standalone
  Yorick plugins (they do not require Yeti to be used).  The
  installation of Yeti depends on that of Yorick which must have been
  installed prior to Yeti.  You'll need at least version 1.6.02 of
  Yorick (for Yorick version 1.5, you can install Yeti 5.3).  You can
  have a look at accompanying file "BUILD-YORICK" to see how to build
  and install Yorick.

  The first installation step consists in the configuration of Yeti
  software suite.  This is done via the "./config.i" script.  In order
  to figure out the different options (and their default values), you
  can just do:

      yorick -batch ./config.i --help

  where "yorick" can also be the full path of the particular Yorick
  executable you want to use for building Yeti.  At least version 1.6
  of Yorick is required to configure/build Yeti.

  By default, Yeti is configured so as to be built as a plugin for the
  executable used to run the "./config.i" script.  You can however
  specify a different Yorick executable with option --yorick=PATH.  If
  you have different versions of Yorick installed, you can
  configure/build/install different versions of Yeti by runnning the
  configure script with option --yorick set to the full path name of
  the considered Yorick executable.

  If you want Yeti plugin for extended regular support, you'll have
  the choice to use a system provided POSIX REGEX library or the GNU
  REGEX library which can be built into the plugin.  This is achieved
  by defining the preprocessor macro HAVE_REGEX to true if you trust
  your system REGEX library.  To use the POSIX REGEX library of your
  system:

      yorick -batch ./config.i [...] --with-regex-defs='-DHAVE_REGEX=1' [...]

  and to built the GNU REGEX library into the plugin (this is the default
  behaviour):

      yorick -batch ./config.i [...] --with-regex-defs='-DHAVE_REGEX=0' [...]

  For instance, here is how to call the configure script to use builtin REGEX
  support and to enable FFTW support (installed in /usr/local) and TIFF
  support (installed in standard locations):

      yorick -batch ./config.i --with-regex \
                  --with-fftw --with-fftw-defs="-I/usr/local/include" \
                  --with-fftw-libs="-L/usr/local/lib -lrfftw -lfftw" \
                  --with-gsl --with-gsl-defs="-I/usr/local/include/gsl" \
                  --with-gsl-libs="-L/usr/local/lib -lgsl -lgslcblas" \
                  --with-tiff --with-tiff-libs="-ltiff"

  In order to check your configuration settings, you can add "--help" as the
  last argument of the call to "./configure".

  After configuration, you can build Yeti and all related plugins by just
  doing:

      make

  In order to install Yeti files into Yorick installation directories, you
  simply do:

      make install


AUTHOR
------
  Eric Thibaut
  Observatoire de Lyon
  9, avenue Charles Andre
  F-69561 Saint Genis Laval Cedex
  thiebaut@obs.univ-lyon1.fr


THANKS
------
  Many things in this software suite were inspired or more or less directly
  imported/translated from  other existing  softwares (see file LICENSE for
  details).


LINKS
-----
 * Yorick: ftp://ftp-icf.llnl.gov/pub/Yorick/

 * FFTW (Fastest Fourier Transform in the West): http://www.fftw.org/
    Please note that since FFTW API has changed with FFTW version 3, only
    FFTW version 2 (latest is 2.1.5) is supported in Yeti (this will change
    soon).

 * GSL (GNU Scientific Library): http://www.gnu.org/software/gsl/

 * LIBTIFF: http://www.libtiff.org/

 * Tcl/Tk: http://www.scriptics.com/products/tcltk/


QUICK REFERENCE OF YETI FUNCTIONS/ROUTINES
------------------------------------------

  Hash tables:
    h_cleanup - delete void members of hash table object
    h_clone - clone a hash table
    h_copy - duplicate hash table object
    h_delete - delete members from a hash table
    h_first - get name of first hash table member
    h_get - get value of hash table member
    h_has - check existence of hash table member
    h_info - list contents of hash table
    h_keys - get member names of a hash table object
    h_list - make a hash table into a list
    h_new - create a new hash table object
    h_next - get name of next hash table member
    h_pop - pop member out of an hash table object
    h_restore_builtin - restore builtin functions
    h_save_symbols - save builtin functions
    h_set - set member of hash table object
    h_set_copy - set member of hash table object
    h_show - display a hash table as an expanded tree
    h_stat - get statistics of hash table object

  Yeti Hierarchical Data (YHD) files (#include "yeti_yhdf.i"):
    yhd_check - check version of YHD file
    yhd_info - print some information about an YHD file
    yhd_restore - restore a hash table object from an YHD file
    yhd_save - save a hash table object into an YHD file

  Regular expressions (#include "yeti_regex.i"):
    regcomp - compile regular expression
    regmatch - match a regular expression against an array of strings
    regmatch_part - peek substrings given indices returned by regmatch
    regsub - substitute regular expression into an array of strings

  Miscellaneous:
    about - search for documentation
    current_include - full path of currently parsed file
    expand_path - expand directory names to absolute paths
    get_path - the counterpart of set_path
    heapsort - sort an array by heap-sort method
    insure_temporary - make sure a variable is not referenced
    is_complex - check if an object is an array of complex value(s)
    is_hash - check if an object is a hash table
    is_integer - check if an object is an array of integer value(s)
    is_list - check if an object is a list
    is_matrix - check if an object is a 2-D array
    is_numerical - check if an object is an array of numerical value(s)
    is_pointer - check if an object is an array of pointer(s)
    is_real - check if an object is an array of floating point value(s)
    is_scalar - check if an object is a scalar array
    is_sparse_matrix - check if an object is a sparse matrix
    is_string - check if an object is an array of string(s)
    is_vector - check if an object is a 1-D array
    pretty_print_string_list - print out a list in columns
    quick_select - find K-th smallest element in an array
    quick_median - find median value (faster than median function)
    quick_interquartile_range - compute inter-quartile range of values
    select_file - interactively select an existing file
    select_item_in_string_list - interactively select an item in a list
    set_alarm - invoke a callback function after some time
    swap - exchange contents of two variables (n copy needed)
    typeIDof - get type identifier of an object
    unref - make a symbol temporary
    yeti_init - setup Yeti internals

  Memory hacking:
    mem_base - get base address of an array object
    mem_copy - copy array data at a given address
    mem_info - print memory information
    mem_peek - make a new array from a base address, type and dimension list
    native_byte_order - compute native byte order

  Files:
    filepath - get full path of a file
    chn_open - open, possibly compressed, file channel.
    chn_seek - set i/o position for a channel.
    chn_read - read data from a channel.
    chn_rewind - go to beginning of a channel file.
    chn_tell - get current i/o position into a channel.
    chn_write - write data to a channel.

  Binary encoding of data:
    get_encoding - get description of binary encoding for various machines
    install_encoding - install binary description into a binary stream
    same_encoding - compare two encoding

  Math/numerical:
    arc - lengh of arc in radians
    cost_l2 - cost function and gradient for l2 norm
    cost_l2l0 - cost function and gradient for l2-l0 norm
    cost_l2l1 - cost function and gradient for l2-l1 norm
    machine_constant - get machine dependent constant (such as EPSILON)
    mvmult - (sparse)matrix-vector multiplication
    round - round to nearest integer
    sinc - cardinal sine: sinc(x) = sin(pi*x)/(pi*x)
    smooth3 - smooth an array by 3-element convolution
    sparse_expand - convert a sparse 'matrix' array into a regular array
    sparse_grow - augment a sparse array
    sparse_matrix - create a new sparse 'matrix'
    sparse_squeeze - convert a regular array into a sparse one
    yeti_convolve - convolution along a given dimension
    yeti_wavelet - "a trou" wavelet decomposition

  Strings:
    strlower - convert array of strings to lower case
    strtrim - remove leading/trailing spaces from an array of strings
    strtrimleft - remove leading spaces from an array of strings
    strtrimright - remove trailing spaces from an array of strings
    strupper - convert array of strings to upper case

  Yorick internals:
    memory_info - display memory used by Yorick symbols
    symbol_exists - check existence of a Yorick symbol
    symbol_info - get some information about existing Yorick symbols
    symbol_names - get names of Yorick symbols
    nrefsof - get number of references of an object
    get_includes - get list of all included files so far

  Graphics:
    window_geometry - get geometry of a Gist window

  Morpho-math operations:
    morph_black_top_hat - perform valley detection
    morph_closing - perform morpho-math closing operation
    morph_dilation - perform morpho-math dilation operation
    morph_erosion - perform morpho-math erosion operation
    morph_opening - perform morpho-math opening operation
    morph_white_top_hat - perform summit detection

  TIFF images (#include "yeti_tiff.i"):
    tiff_open - open TIFF file
    tiff_debug - control printing of TIFF warning messages
    tiff_read_pixels - read pixel values in a TIFF file
    tiff_read_image - read image in a TIFF file
    tiff_read_directory - move to next TIFF "directory"
    tiff_read - read image/pixels in a TIFF file
    tiff_check - check if a file is a readable TIFF file.

  FFTW (#include "yeti_fftw.i"):
    fftw_plan - setup a plan for FFTW
    fftw - computes FFT of an array according to a plan
    cfftw - computes complex FFT of an array
    fftw_indgen - generates FFT indices
    fftw_dist - computes length of spatial frequencies
    fftw_smooth - smooths an array
    fftw_convolve - fast convolution of two arrays
