//************************************************************************
//
//         API for reading and writing IBR formatted TIFF files 
//
//         Written by: Manuel Oliveira 
//
//         Last updated: Jun 24 1997  
//
//
// Reads a TIFF file previously written using UNC-CH IBR image file format
//
// The function returns 0 (zero) if the reading is successful and 1
// otherwise.
//
// The user should provide the following parameters in this order:
//  1. name of the TIFF file to be opened (char *);
//  2. pointer to the area where the image data will be stored (unsigned char**)
//  3. pointer to the area where the disparity data will be stored (float**);
//  4. pointer to the area where the camera data will be stored (float**);
//  5. pointer to the area where the normal vector data will be stored (float**)
//  6. the address where the width of the image will be stored 
//  7. the address where the height of the image will be stored
//
//  The returned values must be interpreted as:
//
//  image is a pointer to an array of unsigned char (byte) with
//  length = 3 x width x height, which contains the RGB values
//  for all pixels in the image, in this order.
//  The array is interpreted as a containing the image written
//  from left to right, and from top to bottom. Thus, the first (top)
//  row is followed by the second, and so on.
//
//  disparity is an array of floats, whose length equals width x height,
//  containing the disparity values associated with each pixel.
//  It should be ordered the same way as the image data itself
//  (left to right, top to bottom).
//
//  normal is an array of floats, with length 3 x width x height,
//  containing the normals at each pixel. If you do not want the
//  the normal vectors to be returned, just pass 0 (DONT_LOAD_NORMALS
//  - see sample program below) as the load_normals parameter. In
//  this case, normal will be set to NULL. It also will be set to null
//  in case the user wants the data, but there is no normal vectors data 
//  stored in the file.
//
//  camera is an array of 12 floats containing, respectively,
//  camera center of projection (x, y, z), vector a (a, y, z),
//  vector b (x, y, z), and vector c (x, y, z).
//
//  width and height correspond, respectively, to the
//  number of columns and rows of the image.
//
//  description is null terminated string containing the image description.
//
//  image_type defines if the image is:       0 - PLANAR
//                                            1 - CYLINDRICAL
//                                            ... 
//                                            to be extended 
//
//  image_type is stored in TIFF field ARTIST
//
// All the memory allocation is done internally by the function. The calling
// function must dispose the allocated memory when it does not need the
// data any more.
//
// Sample program showing the use of the readIBRTIFF function
// 
// #include "ibr_tiffapi.h"
//
// void main (int argc, char* argv[])
// {
//   int width, height, image_type;
//   unsigned char *image;
//   char  *description;
//   float *disparity;
//   float *normal;
//   float *camera;
//  
//   if (readIBRTIFF(argv[1], &image, &disparity, &camera, 
//                   &normal, &width, &height, &description,
//                   LOAD_NORMALS, &image_type) == 0) {
//       ... process image data ...
//   }
//   delete []image;
//   delete []disparity;
//   if (normal != NULL)
//      delete []normal;
//   delete []camera;
//   delete []description;
// }
//
//***********************************************************************
//
//************************************************************************
//
//  Writes a TIFF file using the UNC-CH IBR image file format.
//  The function returns 0 (zero) if the writing is successful and 1
//  otherwise.
//
//  FileName is the name of the file to be created.  
//
//  image is a pointer to an array of unsigned char (byte) with 
//  length = 3 x width x height, which contains the RGB values 
//  for all pixels in the image, in this order. 
//  The array is interpreted as a containing the image written 
//  from left to right, and from top to bottom. Thus, the first (top)
//  row is followed by the second, and so on.
//
//  disparity is an array of floats, whose length equals width x height,
//  containing the disparity values associated with each pixel. 
//  It should be ordered the same way as the image data itself
//  (left to right, top to bottom).
//
//  normal is an array of floats, with length 3 x width x height,
//  containing the normals at each pixel. If you do not need it,
//  just send a NULL pointer as parameter.
//
//  camera is an array of 12 floats containing, respectively,
//  camera center of projection (x, y, z), vector a (a, y, z),
//  vector b (x, y, z), and vector c (x, y, z).
// 
//  width and height correspond, respectively, to the 
//  number of columns and rows of the image. 
//
//  compression defines the compression mode: 1 - none
//                                            2 - CCITTRLE
//                                            3 - CCITTFAX3
//                                            4 - CCITTFAX4
//                                            5 - Lempel-Ziv & Welch encoding
//                                        32766 - NeXT 2-bit RLE
//                                        32773 - Macintosh PackBits encoding   
//  
//  description will contain the image description.
//
//  image_type defines if the image is:       0 - PLANAR
//                                            1 - CYLINDRICAL
//                                            ... 
//                                            to be extended 
//
// Sample program showing the use of the writeIBRTIFF function
// 
// #include "ibr_tiffapi.h"
//
// void main (int argc, char* argv[])
// {
//   int rows, cols, 
//       compression = LEMPELZIV,                //Lempel-Ziv & Welch encoding
//       image_type  = PLANAR;
//   unsigned char *image = new unsigned char[3*rows*cols];
//   float *disp          = new float[rows*cols];
//   float *camera        = new float[12];
//   float *normal        = new float[3*rows*cols];
//   char  *description;
//  
//       ... initialize the data ...
//
//   if (writeIBRTIFF(FileName, image, disp, normal, camera, cols, rows, 
//                    compression, description, image_type) ==0) {
//       ... do whatever you want to do ... 
//   }
//   else
//     printf("Error when trying to write a TIFF file!\n");
//
//   delete []image;
//   delete []disparity;
//   delete []normal;
//   delete []camera;
//   delete []description;
// }
//
//************************************************************************
