#
# INSTALL INSTRUCTIONS
#

FIT3D, R3D, E3D and HIIexplorer are a set of packages to analysize,
reduce and visualize IFS data (mostly fiber-based ones), developed
along several years.

Although they have a somehow "organic" growing, they have been
developed using the main languages/scheme: C (for the most
time-consuming algorithms), and Perl (mostly using PDL,
http://pdl.perl.org/). They use PGPLOT as visualization/plotting
library. We have included the modified PS-options, and adapted to
gfortran this library, so please, download the version at our FTP
(ftp://ftp.caha.es/CALIFA/docs/tutorials/pgplot_ps.tgz), although full
credit has to be given to its creator (T. Pearson,
http://www.astro.caltech.edu/~tjp/pgplot/).

Appart from PDL the Perl script uses different libraries, that can be
found in CPAN (http://www.cpan.org), and external libraries like
CFITSIO (http://heasarc.gsfc.nasa.gov/fitsio/), and Tcl/Tk libraries
(http://www.tcl.tk). 

In most of the cases I have included pre-compiled versions of the 
required tools, and therefore the installation should be easy. However,
for the Perl libraries, it is needed to install all of them. To help you
in the installation process I have included all the required libraries and
tar-files in a single repository:

ftp://ftp.caha.es/CALIFA/docs/tutorials

with the Perl libraries at

ftp://ftp.caha.es/CALIFA/docs/tutorials/Perl

The most important ones are:

Statistics::OLS
Math::FFT
Math::Stat
Math::Spline
Math::Derivative
Math::Approx
Math::Matrix
Astro::FITS::CFITSIO
PGPLOT
PDL


R-Statistical package and the corresponding Perl library:

Statistics::R

are not mandatory but recommended.

#
# Installation Step-by-Step
#
# Optimized for Linux computers. 
#

First you need to download the different tar files at the required
repository. It would be very convinient if you create a single directory
in which all the libraries/package will be installed. It is mandatory
that you have super-user capabilities to install the software.

Let's assume that you have all the packages downloaded in the directory
named "SOFT3D":

setenv SOFT3D /home/myname/SOFT3D

or 

export SOFT3D="/home/myname/SOFT3D"


#
# Basic requirements.
#

You will need the C/C++ and gfortran (GNU compilers gcc and gfortran are ok).

It is required the install the development libraries of X11, zlib, png (libpng), tcl/tk (version 8.5 recommended).
NOTE: If you use Ubuntu use the Ubuntu Software center to install all these libraries (the "dev" version).

Example of installation of this libraries for Ubuntu:

sudo apt-get install libx11-dev
sudo apt-get install tk-dev
sudo apt-get install ppm
sudo apt-get install libghc-zlib-dev
sudo apt-get install libgif-dev
sudo apt-get install libjpeg62-dev

For PNG you should get it from here:
wget -nd http://prdownloads.sourceforge.net/libpng/libpng-1.5.4.tar.gz?download

Then untar, move to the directory and make:
./configure
make
make test
sudo make install


export PGPLOT_DIR=/home/sanchez/2DSoft/pgplot_ps
export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${PGPLOT_DIR}

#
# Installing PGPLOT
# 

The first library to install is PGPLOT. 

You will need to have installed "zlib" "libpng" to install it (see above).




Please download the
"pgplot_ps.tgz" file from the repository and untar it:

tar zxvf pgplot_ps.tgz
cd pgplot_ps
make clean
rm -rf lib*
rm -rf pgtkdemo
rm -rf pgtkdemo.o
rm -rf *pgdemo*
cp makefile.png makefile
make
make cpg

If you find problems with the "pndriver", then you can find in the repository
the following file "makefile.other". Please, download it, and
do:

cp makefile.other makefile
make
make cpng

In some cases the compiler cannot find the Tcl/Th include files (e.g, tk.h).
Please edit the following line in the makefile:

TK_INCL=-I/usr/include  -I/usr/include/tk -I/usr/include/tcl

You should check that indeed this files are in the considered location 
by doing:
find /usr/include/ -name "tk.h" -print
find /usr/include/ -name "tcl.h" -print

They should be at /usr/include/tk or a similar location.

If you do not experience any problem then you have installed
correctly PGPLOT. To test it, you can run any of the pgdemo files:

./pgdemo1

or

./cpgdemo

and finally the tk-demo

./pgtkdemo.tcl

If you get an error saying "I cannot find the dynamic library libpgplot***",
the please, defived the environmental variables below.

If there is no problem you can define your environmenal variables:

setenv PGPLOT_DIR ${SOFT3D}/pgplot_ps/
setenv PGPLOT_DEV /xs

In some computers it is needed to add also the following environmental variables:

setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:${PGPLOT_DIR}

(with "export" for bash shells).

You may experience problems with the tcl/tk libraries, which in the
current "makefile" corresponds to version 8.5. If you have a different
version, you should edit the "makefile", in the following lines:

TK_INCL=-I/usr/include -I/usr/X11R6/include -I/usr/include -I/usr/X11R6/include -I/usr/include/tcl8.5/
TK_LIBS=-L/usr/lib -ltk8.5 -ltcl8.5 -L/usr/X11R6/lib -lX11 -ldl

To know which is the version you have installed, look into the "lib" directory, e.g.,

ls /usr/lib/libtcl*

If no library is reported, you need to install it (using apt-get, the Ubuntu Software Center or similar tools like Yast).


#
# Installing CFITSIO
# 

To install CFITSIO just download the "cfitsio.tgz", move to the "cfitsio" directory, and compile it using:

make

Define the environmental variable:

setenv CFITSIO ${SOFT3D}/cfitsio/

#
# Installing the Perl libraries
#

It is recommended that the Perl libraries are installed in the followign order:

ExtUtils-F77
Statistics::OLS
Math::FFT
Math::Stat
Math::Spline
Math::Derivative
Math::Approx
Astro::FITS::CFITSIO
PGPLOT
PDL

For most of the libraries the sequence is the same. Download the
corresponding tarfile, move to the corresponding directory and 
run the current scripts:

make clean
perl Makefile.PL
make
make test
sudo make install  

You require to be superuser to run the last step. Obviously,
if you find any problem either running the "make" or "make install",
this problem will imply that you cannot install the library.

For the following libraries requires particular care in order to install them:

ExtUtils-F77

This library is absolutely mandatory to install all the rest ones.

Astro::FITS::CFITSIO

It is required to define where the CFITSIO library is located,
by editing the "Makefile.PL", and change the following lines
(if needed):

  $inc = "-I$ENV{CFITSIO} -I$ENV{CFITSIO}/include";
  $libs = "-L$ENV{CFITSIO} -L$ENV{CFITSIO}/lib -lcfitsio -lm";

After that proceed with the previous steps.

PGPLOT

You require "pgplot" to be installed before. Please check
that you have the PGPLOT_DIR variable defined in the corresponding
lines of the "Makefile.PL" file:

   IDIR  => $ENV{PGPLOT_DIR} || '/usr/include,/usr/local/pgplot',
   LDIR  => $ENV{PGPLOT_DIR} || '/usr/lib',
   my $pgplot_dir = defined $ENV{PGPLOT_DIR} ? $ENV{PGPLOT_DIR} : "/usr/lib";

PDL

The Perl Data Language is the key library/routine to work with
the current scripts. So far, the programs work fine with version 2.4.6.
I strongly recommend to install this version and no other.

PDL should be installed using Slatec, i.e., the option:
       WITH_SLATEC => 1,    # Leave it up to PDL to decide    
should be set to one in the "perldl.conf" file.

A "my_perldl.conf" file has been included in the Perl subdirectory
of the repository. Download it before proceed with the installation
of PDL. Then, in the first step of the installation, modify it by

perl Makefile.PL PDLCONF=my_perldl.conf
make
make test
sudo make install  

Once you have installed it, you will have the "perldl" environment
to handle the data interactively (if you want). Just test it by
typing:

"perldl"

Then, in the perldl prompt, type "demo":

perldl> demo
Use:
   demo pdl         # general demo

   demo 3d          # 3d demo (requires TriD with OpenGL or Mesa)
   demo 3d2         # 3d demo, part 2. (Somewhat memory-intensive)
   demo 3dgal       # the 3D gallery: make cool images with 3-line scripts
   demo Tk3d        # Requires the perl Tk module

   demo pgplot      # PGPLOT graphics output (Req.: PGPLOT)
   demo OOplot      # PGPLOT OO interface    (Req.: PGPLOT)

   demo transform   # Coordinate transformations (Req.: PGPLOT)
   demo cartography # Cartographic projections (Req.: PGPLOT)

   demo bad         # Bad-value demo (Req.: bad value support)
   demo bad2        # Bad-values, part 2 (Req.: bad value support and PGPLOT)


And finally "demo pgplot". You should see a set of examples 
of the use PGPLOT under the PDL environment.


#
# Installing E3D
#

E3D it is the Euro3D visualization tool (Sanchez 2004;
http://www.aip.de/Euro3D/E3D/). You can download the last stable
version from the Euro3D webpage, however, I distribute here a pre-compiled
previous version (that work fine with most of the data). 

(A) Installing the pre-compiled version. 

For most of the 64bits computers this precompiled version works
fine. Just download the file "E3D_v1.3b_linux.tgz", and decompress
it. It will create an "E3D" directory. Move to this directory and run
the script:

./install_static.pl

The follow the instructions indicated in the terminal: 

(1) Add '${SOFT3D}/E3D' to your path
setenv PATH ${PATH}:${SOFT3D}/E3D

(2) Define IFU_DEFAULT_FMT as "Euro3D" in your login script:
tcsh: setenv IFU_DEFAULT_FMT "Euro3D";
bash: export IFU_DEFAULT_FMT="Euro3D";
(3) run 'tk_e3d.tcl'

Do not relax at this level. Download a datacube from the CALIFA DR1 webpage
http://califa.caha.es/DR1
and "import" it in the visualization tool. If you do not get any error message,
then you have installed propertily E3D.

You may get different error messages, some of them related to the lack
of a particular C-library. In some cases they are solved by installing
the corresponding library. However, if you get several messages, I
recommend you to re-compile E3D

E3D has its own user guide with some examples, included in the
distribution "E3D.ps". 

There is a version prepared for Mac users ("E3D_MacOs.tgz"), in the FTP.

(B) Compiling the source code of E3D.

If you cannot install the pre-compiled version then you should compile
and install the source code. First you need to download the following files:

E3D_io_LCL-1.3b.tar.gz
e3d-1.3b.tar.gz

The first one is a modified version of the Lyon-C-Libraries, developed at the
Observatory of Lyon (A.Pecontal et al.). To install them follow the next steps:

tar zxvf E3D_io_LCL-1.3b.tar.gz
mv E3D_io_LCL-1.3 E3D_io_LCL-1.3b
cd E3D_io_LCL-1.3b
./configure
make
setenv IFU_PATH "${SOFT3D}/E3D_io_LCL-1.3b";
setenv IFU_DEFAULT_FMT "Euro3D";

Then test the installation by going to the directory:
cd ${SOFT3D}/E3D_io_LCL-1.3b/checklib/exec
and running the program:
./check_spec_io
./chec_table_io

If all tests are ok, you have the LCL-library installed.

The we will install E3D, itself:
tar zxvf e3d-1.3b.tar.gz
cd e3d-1.3b

Now we have to edit the configuration file to indicate where we have stored the PGPLOT libraries and which version of tcl and tk we are using:

emacs add_defs/makedefs.local (or "vi")

goes to the line defining V3D_LIBS, and edit it to look like:

V3D_LIBS =  -static-libgcc ${SOFT3D}/sda2/pgplot/libtkpgplot.a ${SOFT3D}/sda2/pgplot/libcpgplot.a ${SOFT3D}/sda2/pgplot/libpgplot.a -L/usr/local/lib -ltk8.5 -ltcl8.5 -L$(topdir)/pkg/v3d/obj -lmy_grid -L/usr/X11R6/lib -lX11

You can identify which Tcl/Tk library you have by looking at the /usr/lib directory:
ls /usr/lib/libtk*

Another source of problem is the location of the X11 libraries (at
/usr/X11R6/lib in this example).

After that, you compile E3D:
./configure
make

You should define the following environmental variables:

setenv PATH ${PATH}:${SOFT3D}/e3d-1.3b/user/bin/
setenv IFU_DEFAULT_FMT "Euro3D";

After that, you can run E3D, by calling "tk_e3d.tcl".

#
# Installing FIT3D
#

FIT3D is a package of scripts that allows to analyze 3D data (RSS,
cubes, individual spectra), created by S.F.Sanchez
(http://www.caha.es/sanchez/FIT3D/), with extensive help of
F.Rosales-Ortega and B.Husemann.

To install it, following the next steps:

1) Download the FIT3D.tgz tar-file from the repository.

2) Untar the file:
tar zxvf FIT3D.tgz

3) Define the environmental variable:

setenv FIT3D_PATH "${SOFT3D}/FIT3D" # for tcshell
export FIT3D_PATH="${SOFT3D}/FIT3D"; # for basch shell

5) Add the corresponding directories to your PATH

setenv PATH ${PATH}:${SOFT3D}/FIT3D/bin
setenv PATH ${PATH}:${SOFT3D}/FIT3D/scripts


4) move to the corresponding directory:

cd FIT3D/examples

run the script:

fit_spec_back spec_single.txt Ha_NII_He_SII.config

and

fit_spec_back.pl spec_single.txt none 6500 6800 none 0 none Ha_NII_He_SII.config 66/xs

It no error is reported, you have FIT3D running.

5) If you have an error related with the 1st script, you may re-compile the
source code:

cd ${SOFT3D}/FIT3D/src
source compile.sh

You may have some "warnings" in the compilation, but no errors. If you get 
no errors, then you can repeat the testing scripts (4).

6) If you have an error related to the 2nd script, most probably you
do not have some of the required PERL libraries installed (read before
in this document).

If you cannot solve the problem, please contact me.

#
# Installing HIIexplorer
#

HIIexplorer is a package for detecting and extracting the integrated
spectra of HII regions from IFS datacubes. Together with FIT3D can be
used to derive the physical parameters of these regions
(http://www.caha.es/sanchez/HII_explorer).

To install it:

1) Download the corresponding file from the repository "HII_analyzer.tgz"

2) Untar it:
tar zxvf HII_analyzer.tgz

3) Define the corresponding environmental variables:

setenv HIIEXPLORER_PATH ${SOFT3D}/HII_analyzer
setenv PATH ${PATH}:${SOFT3D}/HII_analyzer

4) Test the installation:

cd ${HIIEXPLORER_PATH}
./HII_recover.pl
USE: reg_spec.pl Ha_map.fits FLUX_LIMIT_PEAK MAX_DIST_PEAK FRAC_PEAK MIN_FLUX SEGFILE.fits DIFFUSE_MASK.fits

If you get not error message, you have HIIExplorer installed correctly.

#
# IFSview.py
#

IFSview is a single monolitic script to visualize datacubes, coded in python.

The instructions of how to install it are described in its webpage:
http://www.caha.es/sanchez/IFSview/index.html