GenSynthMatchesRig.cpp

/*
This file is part of the BIAS library (Basic ImageAlgorithmS).

Copyright (C) 2003-2009    (see file CONTACT for details)
  Multimediale Systeme der Informationsverarbeitung
  Institut fuer Informatik
  Christian-Albrechts-Universitaet Kiel


BIAS is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.

BIAS is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with BIAS; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*/

#include <iostream>
#include <sstream>
#include <string>
#include <climits>
#include <cfloat>

#include <Base/Debug/LogFacility.hh>
#include "GenSynthMatchesRig.hh"
#include <Base/ImageUtils/ImageDraw.hh>
#include <Geometry/PMatrix.hh>

using namespace BIAS;
using namespace std;

/**
   Prints the contained GenSynthMatches objects to the given ostream.
*/
ostream& BIAS::operator<<(ostream& os, const GenSynthMatchesRig& m)
{
  std::vector<BIAS::GenSynthMatches> cams = m.GetCams();
  std::vector<BIAS::GenSynthMatches>::iterator it;
  int i;
  for (it = cams.begin(), i=0;
       it != cams.end();
       it++, i++) {
    os << "Camera " << i << ": " << std::endl
       << *it << std::endl;
  }
  return os;
}

/**
   Constructor. Registers the needed parameters in the param object. The values
   can then be filled externally, e.g. by a param file. The object GenMatches_
   of type #BIAS::GenSynthMatches is initialized with the param object - this
   way GenMatches will register all parameters needed for a GenSynthMatches
   object in the argument of the constructor. In #AddParameters_() the special
   parameters of this class will become registered.
   @param para A parameter object.
   @see BIAS::Param for information on Param objects.
   @note The parameters should be set externally. First the parameters have to
   be registered. Then, before creating matches, the values should be filled
   by the user (e.g. reading the parameters from a file).
 */
GenSynthMatchesRig::GenSynthMatchesRig(Param &para)
  :  GenMatches_(para)
{
  allParams_=&para;
  //change the param values - moving points are not yet supported
  *para.GetParamInt("NumPoints") = *para.GetParamInt("NumPoints")
    - *para.GetParamInt("NumMovingPoints");
  *para.GetParamInt("NumMovingPoints") = 0;
  *para.GetParamInt("NumMovingObjects") = 0;
  //add parameters needed for this class
  AddParameters_(*allParams_);
}

/**
  Default destructor...
*/
GenSynthMatchesRig::~GenSynthMatchesRig()
{}

/**
  Here the values of the param (object/file) are assigned to the member
  variables with the #GetParameters_() method. In the next step, the vector
  #SlaveCamsGlobal_ containing the global poses of the slave cameras is being
  filled. The global poses are computed by applying the movement of the
  master camera (first camera) to the slave cameras (which have known relative
  transforms to the master camera).
  @pre The vector containing the moving information must contain at least
  as many elements as number of images given in the param object.
  @pre The number of cameras must not be greater then
  #GENSYNTHMATCHESRIG_MAX_NR_OF_CAMERAS.
 */
void GenSynthMatchesRig::Setup_() {
  //read the parameters from the param object
  GetParameters_();

  int numImages = *(allParams_->GetParamInt("NumImages"));

  //for each slave cam
  //- the # of slave cams is # of cams without the master cam
  for (int slavecam = 0; slavecam < *NumCameras_-1; slavecam++) {

    std::vector<std::map<std::string, double> > tmpVec;
    //for each timestep
    for (int timestep = 0; timestep < numImages; timestep++) {
      //get the coordinate transform of the master camera:
      BIAS::Vector3<double> CMaster(MasterCenterX_[timestep],
                                    MasterCenterY_[timestep],
                                    MasterCenterZ_[timestep]);
      BIAS::RMatrix RMaster(BIAS::MatrixIdentity);

      RMaster.SetXYZ(MasterAnglesX_[timestep],
                     MasterAnglesY_[timestep],
                     MasterAnglesZ_[timestep]);
      //set the (global) master camera transform to the given center
      //and angles
      RMatrix RMasterInv = RMaster;
      RMasterInv.TransposeIP();
      BIAS::Matrix4x4<double> masterTransform(RMaster, CMaster);
      //and get the inverse of the master coordinate transform:
      RMaster.TransposeIP();
      BIAS::Vector3<double> CMasterInv = RMaster * (-1.0 * CMaster);
      BIAS::Matrix4x4<double> masterTransformInv(RMaster, CMasterInv);

      //get the relative transform between master and current slave camera:
      BIAS::Vector3<double> CSlave(SlaveCamsRelative_[slavecam]["relPosX"],
                                   SlaveCamsRelative_[slavecam]["relPosY"],
                                   SlaveCamsRelative_[slavecam]["relPosZ"]);

      BIAS::RMatrix RSlave = BIAS::RMatrix(BIAS::MatrixIdentity);
      RSlave.SetXYZ(SlaveCamsRelative_[slavecam]["relRotX"],
                    SlaveCamsRelative_[slavecam]["relRotY"],
                    SlaveCamsRelative_[slavecam]["relRotZ"]);

      //set the local transform relative to the master camera:
      //      BIAS::Matrix4x4<double> slaveTransform(RSlave, RSlave * CSlave);
            RMatrix RSlaveInv = RSlave.Transpose();
      BIAS::Matrix4x4<double> slaveTransform(RSlave, CSlave);

      BIAS::Matrix4x4<double> slaveTransformInv(RSlaveInv, RSlaveInv * (-1.0 * CSlave));

      //////////////////
      /*
      BIAS::Vector3<double> CMaster2(MasterCenterX_[timestep],
                                    MasterCenterY_[timestep],
                                    MasterCenterZ_[timestep]);
      BIAS::RMatrix RMaster2(BIAS::MatrixIdentity);

      RMaster2.SetXYZ(MasterAnglesX_[timestep],
                      MasterAnglesY_[timestep],
                      MasterAnglesZ_[timestep]);

      BIAS::Vector3<double> CSlave2(SlaveCamsRelative_[slavecam]["relPosX"],
                                    SlaveCamsRelative_[slavecam]["relPosY"],
                                    SlaveCamsRelative_[slavecam]["relPosZ"]);

      BIAS::RMatrix RSlave2 = BIAS::RMatrix(BIAS::MatrixIdentity);
      RSlave2.SetXYZ(SlaveCamsRelative_[slavecam]["relRotX"],
                     SlaveCamsRelative_[slavecam]["relRotY"],
                     SlaveCamsRelative_[slavecam]["relRotZ"]);

      RMatrix RSlaveGlobal2 = RMaster2 * RSlave2;

      BIAS::Vector3<double> SlaveCGlobal =
        RMaster2 * CSlave2 + CMaster2;

      std::map<std::string, double> tmpMap;
      //get the global center of the slave cam - read from the global
      //coord transform matrix
      tmpMap["GlobalPosX"] = SlaveCGlobal[0];
      tmpMap["GlobalPosY"] = SlaveCGlobal[1];
      tmpMap["GlobalPosZ"] = SlaveCGlobal[2];

      double aX, aY, aZ;
      RSlaveGlobal2.GetRotationAnglesXYZ(aX, aY, aZ);
      tmpMap["GlobalAnglesX"] = aX;
      tmpMap["GlobalAnglesY"] = aY;
      tmpMap["GlobalAnglesZ"] = aZ;

      ///////////////////
      */
      //get global coord transform of the current slave camera:
      BIAS::Matrix4x4<double> TGlobal = masterTransform * slaveTransform;
      //        * masterTransformInv;
      // TGlobal = BIAS::Matrix4x4<double>(RSlave * RMaster, RMaster * CSlave);
      //    cout << TGlobal;
      //map to store the computed global pose of the current slave camera
      std::map<std::string, double> tmpMap;
      //get the global center of the slave cam - read from the global
      //coord transform matrix
      tmpMap["GlobalPosX"] = TGlobal[0][3];
      tmpMap["GlobalPosY"] = TGlobal[1][3];
      tmpMap["GlobalPosZ"] = TGlobal[2][3];

      //set up the rotation matrix of the global transform of the slave camera
      BIAS::Matrix<double> RGlobal(3,3);
      RGlobal[0][0] = TGlobal[0][0];
      RGlobal[0][1] = TGlobal[0][1];
      RGlobal[0][2] = TGlobal[0][2];

      RGlobal[1][0] = TGlobal[1][0];
      RGlobal[1][1] = TGlobal[1][1];
      RGlobal[1][2] = TGlobal[1][2];

      RGlobal[2][0] = TGlobal[2][0];
      RGlobal[2][1] = TGlobal[2][1];
      RGlobal[2][2] = TGlobal[2][2];

      //convert to a matrix of type rotation matrix (BIAS::RMatrix).
      BIAS::RMatrix RGlobal2(RGlobal);
      //read the global rotation angles to the vectors of the slave camera.
      double aX, aY, aZ;
      RGlobal2.GetRotationAnglesXYZ(aX, aY, aZ);
      tmpMap["GlobalAnglesX"] = aX;
      tmpMap["GlobalAnglesY"] = aY;
      tmpMap["GlobalAnglesZ"] = aZ;

      /*     cout << "GlobalX: " << TGlobal[0][3]
           << "GlobalY: " << TGlobal[1][3]
           << "GlobalZ: " << TGlobal[2][3]
           << "AngleX: " << aX
           << "AngleY: " << aY
           << "AngleZ: " << aZ << endl;
      */
      //store the global pose of the current slave cam in the vector
      //containing all poses (for each timestep) of that slave camera.
      tmpVec.push_back(std::map<std::string, double>(tmpMap));
    } //for each time step
    //store the current slave cam in the vector containing the poses of all
    //slave cams at each time step.
    SlaveCamsGlobal_.push_back(VecOMapOStrDbl(tmpVec));
  } //for each slave cam

#ifdef BIAS_DEBUG
  /*
  //print out the global poses of the slave cameras:
  cout << *NumCameras_ << "x" << numImages << " Images: " << endl;
  std::vector<VecOMapOStrDbl >::iterator slaves;
  std::vector<std::map<std::string, double> >::iterator timest;
  std::map<std::string, double>::iterator data;
  int a,b;
  for (slaves = SlaveCamsGlobal_.begin(), a=0;
       slaves != SlaveCamsGlobal_.end(); slaves++, a++) {
    cout << "slave cam " << a << ":" << endl;
    for (timest = ((*slaves).vecOMaps).begin(), b=0;
         timest != ((*slaves).vecOMaps).end();
         timest++, b++) {
      cout << "\t" << "timestep " << b << ":" << endl;
      for (data = (*timest).begin(); data != (*timest).end(); data++) {
        cout << "\t\t" << data->first << " ==> " << data->second << endl;
      }
    }
  }
  */
#endif
}

/**
   Read the parameters from the param object. The relative transformations
   of the slave cameras to the master camera are stored in #SlaveCamsRelative_.
*/
void GenSynthMatchesRig::GetParameters_()
{
#ifdef BIASASSERT_ISACTIVE
  int numImages = *(allParams_->GetParamInt("NumImages"));
#endif

  NumCameras_ = allParams_->GetParamInt("NumCameras");
  if (*NumCameras_ > GENSYNTHMATCHESRIG_MAX_NR_OF_CAMERAS) {
    BIASERR("Only " << GENSYNTHMATCHESRIG_MAX_NR_OF_CAMERAS << " allowed...");
    BIASABORT;
  }
  //these values do exist, because they will be filled by the GenSynthMatches
  //class. They can be reset by changing the values of the param object passed
  //to the constructor.
  MasterCenterX_ = *(allParams_->GetParamVecDbl("MotionVecX"));
  BIASASSERT(MasterCenterX_.size() >= numImages);
  MasterCenterY_ = *(allParams_->GetParamVecDbl("MotionVecY"));
  BIASASSERT(MasterCenterY_.size() >= numImages);
  MasterCenterZ_ = *(allParams_->GetParamVecDbl("MotionVecZ"));
  BIASASSERT(MasterCenterZ_.size() >= numImages);
  MasterAnglesX_ = *(allParams_->GetParamVecDbl("RotVecX"));
  BIASASSERT(MasterAnglesX_.size() >= numImages);
  MasterAnglesY_ = *(allParams_->GetParamVecDbl("RotVecY"));
  BIASASSERT(MasterAnglesY_.size() >= numImages);
  MasterAnglesZ_ = *(allParams_->GetParamVecDbl("RotVecZ"));
  BIASASSERT(MasterAnglesZ_.size() >= numImages);

  std::map<std::string, double> myMap;
  stringstream oss;
  SlaveCamsRelative_.clear();
  for (int i = 1; i <= GENSYNTHMATCHESRIG_MAX_NR_OF_CAMERAS; i++) {
    oss << i;
    //X component
    myMap["relPosX"] =
      *(allParams_->GetParamDouble("Cam" +  oss.str() + "_RelPosX"));
    //Y component
    myMap["relPosY"] =
      *(allParams_->GetParamDouble("Cam" +  oss.str() + "_RelPosY"));
    //Z component
    myMap["relPosZ"] =
      *(allParams_->GetParamDouble("Cam" +  oss.str() + "_RelPosZ"));
    //rotation angle X
    myMap["relRotX"] =
      *(allParams_->GetParamDouble("Cam" +  oss.str() + "_RelRotX"));
    //rotation angle Y
    myMap["relRotY"] =
      *(allParams_->GetParamDouble("Cam" +  oss.str() + "_RelRotY"));
    //rotation angle Z
    myMap["relRotZ"] =
      *(allParams_->GetParamDouble("Cam" +  oss.str() + "_RelRotZ"));

    SlaveCamsRelative_.push_back(myMap);
    oss.str(""); //clear the stream
  } //for each slave camera
}

/**
  Generates 3D Points an creates the 2D matches for each camera at each time
  step. At first #Setup_() is beenig called to compute the poses of the slave
  cameras in the global coord system (which hast its origin at the center of
  the master camera).
  For each camera an BIAS::GenSynthMatches object will be created. The object
  assigned to the master cam creates random 3D Points which will be passed to
  the slave cameras. So all cameras work with the same 3D points and try to
  generate 2D matches for them. If a 3D point has no match with an image plane
  of a camera, the 3D point will be replaced. After 1000 reties the computation
  will abort.
  @return 0, if OK. -1, if too many iterations.
  @todo Moving objects not yet supported.
*/
int GenSynthMatchesRig::CreateMatches()
{
  //allParams_->ShowData();
  Setup_();
  //GenSynthMatches object for the master camera
  BIAS::GenSynthMatches masterCam(*allParams_);

  //create 3D points for the master camera
  masterCam.Create3DPoints();

  int res = -1; //result of the creation of the 2D matches.
  int counter = 0; //counter - not to loop forever...

  while (res != 0 && counter < 1000) {
    //create matches for the newly generated point(s)
    int index;
    if (masterCam.CreateMatches(index) ==
        GSM_RETURN_ERROR_HANDLING_STATIC_POINT) {
      BIASERR("Could not set up master camera.");
      BIASABORT;
    }

    //get the newly generated static 3D points of the master camera
    std::vector<BIAS::HomgPoint3D> staticPoints;
    masterCam.GetStatic3DPoints(staticPoints);

    //get the newly generated moving 3D points of the master camera
    std::vector<BIAS::HomgPoint3D> movingPoints;
    masterCam.GetMoving3DPoints(movingPoints);

    //store the GenSynthMatches object in the vector
    CamMatches_.push_back(masterCam);

    //for each slave camera (starting with 1 because 0 is the master camera)
    for (int slaveCamIndex = 1; slaveCamIndex < *NumCameras_; slaveCamIndex++){
      //update the parameters for the current slave cam. (cam motion)
      UpdateParams_(slaveCamIndex);
      //create a new object for the slave cam
      BIAS::GenSynthMatches slaveCam(*allParams_);
      slaveCam.CreateCamMovement();
      slaveCam.CreateMovingTransforms();
      //set up the 3D points equal to the 3D points of the master camera
      slaveCam.SetStatic3DPoints(staticPoints);
      slaveCam.SetMoving3DPoints(movingPoints);
      //Create 2D matches for the slave cam
      res = slaveCam.CreateMatches(index);
      //store the matches
      CamMatches_.push_back(slaveCam);
      //if an error occured (a 3D point could not be projected into the current
      //image plane) the bad point will be replaced in the master cam an all
      //computation for the slave cams will restart.
      if (res == GSM_RETURN_ERROR_HANDLING_STATIC_POINT) {
        BLD("bad index was " << index << " static object not seen "
            << "in slaveCam "
            << slaveCamIndex
            << " - trying again... (" << counter+1 << "/1000)" << endl);
        CamMatches_.clear();
        //generate a new 3D point and replace the bad 3D point
        masterCam.CreateStatic3DPoint(index);
        counter++;
        break;
      } else if (res == GSM_RETURN_ERROR_HANDLING_MOVING_POINT) {
         BLD("bad index was " << index << " moving object not seen "
            << "in slaveCam "
            << slaveCamIndex
            << " - trying again... (" << counter+1 << "/1000)" << endl);
        CamMatches_.clear();
        //generate a new 3D point and replace the bad 3D point
        masterCam.CreateMoving3DPoint(index);
        counter++;
        break;
      } else if (res != GSM_RETURN_OK) {
        BIASERR("Unexpected result ( " << res << ")");
        BIASABORT;
      }
    } //for each slave camera
  } //while
  if (counter >= 1000) {
    BIASERR("Could not find a solution for all cameras (1000 trials). Maybe no"
            << " common viewing volume.");
    return -1;
  }
  return 0;
}


/**
  Updates the parameters for a given slave camera. The parameters are updated
  before the 2D matches are computed for a #BIAS::GenSynthMatches object of
  a slave camera. The values of the poses (motion/rotation vectors) of the
  camera of the #BIAS::GenSynthMatches object will be filled with the global
  poses of the given slave cam.
  @param[in] camID The ID of the camera to be updated.
  @note The master cam must not be updated. All values are set initially.
*/
void GenSynthMatchesRig::UpdateParams_(int camID) {
  //be sure we don't have the master cam here.
  BIASASSERT(camID > 0);
  //get the number of images to be computed
  int numImages = *(allParams_->GetParamInt("NumImages"));
  //set up the global pose vectors with the needed length
  BIAS::Vector<double> centerX(numImages);
  BIAS::Vector<double> centerY(numImages);
  BIAS::Vector<double> centerZ(numImages);
  BIAS::Vector<double> anglesX(numImages);
  BIAS::Vector<double> anglesY(numImages);
  BIAS::Vector<double> anglesZ(numImages);

  //master cam is ID 0. slave cams start with 1, but are stored starting with
  //index 0 in the SlaveCamsGlobal_ vector.
  std::vector<std::map<std::string, double> > currentSlave =
    SlaveCamsGlobal_[camID -1].vecOMaps;
  //for number of images
  for (int i = 0; i < numImages; i++) {
    //set up the vectors with the global poses of the slave cam
    centerX[i] = currentSlave[i]["GlobalPosX"];
    centerY[i] = currentSlave[i]["GlobalPosY"];
    centerZ[i] = currentSlave[i]["GlobalPosZ"];
    anglesX[i] = currentSlave[i]["GlobalAnglesX"];
    anglesY[i] = currentSlave[i]["GlobalAnglesY"];
    anglesZ[i] = currentSlave[i]["GlobalAnglesZ"];
  }

#ifdef BIAS_DEBUG
  /*
  cout << "Centers of slaveCam " << camID << ":";
  cout << centerX << "/" << centerY <<"/" <<  centerZ << endl;
  cout << "angles:";
  cout << anglesX << "/" << anglesY <<"/" <<  anglesZ << endl;
  */
#endif

  //assign the vectors to the parameters
  *(allParams_->GetParamVecDbl("MotionVecX")) = centerX;
  *(allParams_->GetParamVecDbl("MotionVecY")) = centerY;
  *(allParams_->GetParamVecDbl("MotionVecZ")) = centerZ;
  *(allParams_->GetParamVecDbl("RotVecX")) = anglesX;
  *(allParams_->GetParamVecDbl("RotVecY")) = anglesY;
  *(allParams_->GetParamVecDbl("RotVecZ")) = anglesZ;
  //  cout << "centerX: " << centerX << " ParamCenterX: "
  //   << *(allParams_->GetParamVecDbl("MotionVecX")) << endl;
}

/**
  Create images for all cameras showing the matches.
  @param[out] imgs The vector containing the computed images. The image will
  be drawn based the ground truth data.
  @param[in] minindex The index (time step) to start with.
  @param[in] maxindex The index (time step) to end with.
 */
void GenSynthMatchesRig::DrawTrue(std::vector<Image<unsigned char> >
                                       &imgs, int minindex, int maxindex) const
{
  for (int i = 0; i < *NumCameras_; i++) {
    Image<unsigned char> im;
    CamMatches_[i].DrawTrue(im, minindex, maxindex);
    imgs.push_back(im);
  }
}

/**
   Create an image for a camera.
   @param[out] img The resulting image. The image will be drawn
   based on the ground truth data.
   @param[in] minindex The index (time step) to start with.
   @param[in] maxindex The index (time step) to end with.
   @param[in] camIndex The index of the camera to get the image from.
*/
void GenSynthMatchesRig::DrawTrue(Image<unsigned char> &img, int minindex,
                                  int maxindex, int camIndex) const
{
  if (camIndex < (int)CamMatches_.size() && camIndex >= 0) {
    CamMatches_[camIndex].DrawTrue(img, minindex, maxindex);
  } else {
    BIASERR("Could not draw image for camera at index " << camIndex << ". "
            << "only " << CamMatches_.size() << " cameras available.");
  }
}

/**
  Create images for all cameras showing the matches.
  @param[out] imgs The vector containing the computed images. The image will
  be drawn based on the noisy data.
  @param[in] minindex The index (time step) to start with.
  @param[in] maxindex The index (time step) to end with.
 */
void GenSynthMatchesRig::DrawNoisy(std::vector<Image<unsigned char> > &imgs,
                                   int minindex, int maxindex) const
{
 for (int i = 0; i < *NumCameras_; i++) {
    Image<unsigned char> im;
    CamMatches_[i].DrawNoisy(im, minindex, maxindex);
    imgs.push_back(im);
  }
}

/**
   Create an image for a camera.
   @param[out] img The resulting image. The image will be drawn
   based on the noisy data.
   @param[in] minindex The index (time step) to start with.
   @param[in] maxindex The index (time step) to end with.
   @param[in] camIndex The index of the camera to get the image from.
*/
void GenSynthMatchesRig::DrawNoisy(Image<unsigned char> &img, int minindex,
                                   int maxindex, int camIndex) const
{
  if (camIndex < (int)CamMatches_.size() && camIndex >= 0) {
    CamMatches_[camIndex].DrawNoisy(img, minindex, maxindex);
  } else {
    BIASERR("Could not draw image for camera at index " << camIndex << ". "
            << "only " << CamMatches_.size() << " cameras available.");
  }
}

/**
   Write the necessary components of this object to an xml file. These are:
   - The contained GenStynthMatches objects, which is stored by setting a
   file name in the attribute of each "Camera" node. These will be stored
   to <given_filename>.cam0, <given_filename>.cam1, ...
   - The number of cameras to be used, which is stored by the number of
   "Camera" nodes written to the xml file.
   @param[in] file The file name to store the file. The extension (.xml) should
   be contained in the file name.
   @return < 0, if an error occured.
   @see Read() to read this object from a file and to see an example xml file.
 */
int GenSynthMatchesRig::Write(string file) const
{
#ifdef BIAS_HAVE_XML2
  XMLIO xmlObject;
  stringstream camFile;

  xmlNodePtr rootNode = xmlObject.create("GenSynthMatchesRigData");
  xmlObject.addAttribute(rootNode, "Version", 0.1);
  for (unsigned int i=0; i<CamMatches_.size(); i++) {
    camFile << file.c_str() << ".cam" << i;
    xmlNodePtr camNode = xmlObject.addChildNode(rootNode, "Camera");
    xmlObject.addAttribute(camNode, "FileName", camFile.str());

    CamMatches_[i].Write(camFile.str());
    camFile.str("");
  }
  return xmlObject.write(file);

#else
  BIASERR("BIAS_HAVE_XML2 must be defined to write to a file.");
  BIASABORT;
  return -1;
#endif
}

/**
   Fill the necessary parts of this object from a file. These are:
   - The contained GenStynthMatches objects
   - The number of cameras to be used
   @param[in] The file name to read from.
   @return
   -  0: all right
   - -1: error reading from file
   - -2: no child nodes of root node found
   - -3: attribute not found in the child node

   Here is an example for an xml file:
   @code
   <?xml version="1.0" encoding="ISO-8859-1"?>
     <GenSynthMatchesRigData Version="0.1">
       <Camera FileName="dataRig.xml.cam0"/>
       <Camera FileName="dataRig.xml.cam1"/>
     </GenSynthMatchesRigData>
   @endcode
   @todo Check if the nodes and attributes have the expected names.
*/
int GenSynthMatchesRig::Read(string file)
{
#ifdef BIAS_HAVE_XML2
  //reset the GenSynthMatches
  CamMatches_.clear();
  XMLIO xmlObject;
  //get the root node and fill xmlobject with the read xml tree
  xmlNodePtr rootNode = xmlObject.read(file);
  if (! rootNode) {
    BIASERR("GenSynthMatchesRig: Error reading file " << file);
    return -1;
  }
  std::vector<xmlNodePtr> cams;
  //get all child nodes of the root node
  xmlObject.GetChildren(rootNode, cams);
  if (cams.size() == 0) {
    BIASERR("Child Node of root node (named \"Camera\") expected but does "
            << "not exist.");
    return -2;
  }

  int i; //count the number of cams
  //for each child node
  for (i = 0; i < (int)cams.size(); i++) {
    xmlAttrPtr fileNameAttr = xmlObject.getFirstAttribute(cams[i]);
    if (! fileNameAttr) {
      BIASERR("GenSynthMatchesRig: All Camera nodes must have an \"FileName\""
              << "attribute.");
      return -3;
    }
    //get the file name
    std::string fileName = xmlObject.getAttributeValueString(fileNameAttr);

    GenSynthMatches cam(*allParams_);
    //read GenSynthMatches object from file
    cam.Read(fileName);

    //store the object
    CamMatches_.push_back(cam);
  }

  //store the number of cameras
  *NumCameras_ = i;

  return 0;

#else
  BIASERR("BIAS_HAVE_XML2 must be defined to read from a file.");
  BIASABORT;
  return -1;
#endif
}


/**
   Print out the camera poses of each camera and each time step
*/
void GenSynthMatchesRig::PrintCamPoses_() {
  cout << "master Cam:" << endl
       << "[ " << MasterCenterX_ << ", " << MasterCenterY_ << ", "
       << MasterCenterZ_ << " ]" << "  " << "[ " << MasterAnglesX_
       << ", " << MasterAnglesY_ << ", " << MasterAnglesZ_ << " ]" << endl;
  int i;
  std::vector<std::map<std::string, double> >::iterator it;
  for (it = SlaveCamsRelative_.begin(), i = 0;
       it!= SlaveCamsRelative_.end(); it++, i++) {
    cout << "slave Cam " << i << ":" << endl
         << "[ " << (*it)["relPosX"] << ", " << (*it)["relPosY"] << ", "
         << (*it)["relPosZ"] << " ]" << "  " << "[ " << (*it)["relRotX"]
         << ", " << (*it)["relRotY"] << ", " << (*it)["relRotZ"] << " ]"
         << endl;
  }
}

/**
  Register needed parameters. The parameters needed by the
  #BIAS::GenSynthMatches objects are registered by a dummy object in the
  constructor.
  @param[out] para The parameter object to be updated.
 */
void GenSynthMatchesRig::AddParameters_(Param &para)
{
  int grp;

  if (para.CheckParam("NumImages")){
    grp=para.GetGroupID("NumImages");
  } else {
    grp=para.GetFreeGroupID();
  }
  //  cerr << "GenSynthMatches: using ID "<<grp<<" for group num\n";


  //add NumCameras to group numbers
  if (para.CheckParam("NumCameras")){
    NumCameras_ = para.GetParamInt("NumCameras");
  } else {
    NumCameras_ = para.AddParamInt("NumCameras", "number of cameras used",
                     2, 0, INT_MAX, 0, grp);
  }
  if (para.IsUsedGroupID(grp))
    para.SetGroupName(grp, "numbers");

  //add relative positions and rotations of slave cameras
  grp = para.GetFreeGroupID();
  std::map<std::string, double> myMap;
  stringstream oss;
  //for each (possible) slave camera
  for (int i = 1; i <= GENSYNTHMATCHESRIG_MAX_NR_OF_CAMERAS; i++) {
    oss << i;

    //X component
    if ( para.CheckParam("Cam" +  oss.str() + "_RelPosX") ){
      myMap["relPosX"] =
        *(para.GetParamDouble("Cam" +  oss.str() + "_RelPosX"));
    } else {
      myMap["relPosX"] =
        *(para.AddParamDouble("Cam" + oss.str() + "_RelPosX",
                              "relative tranlation (X component)"
                              "of camera " + oss.str(),
                              2.0, 0.0, DBL_MAX, 0, grp));
    }

    //Y component
    if ( para.CheckParam("Cam" +  oss.str() + "_RelPosY") ){
      myMap["relPosY"] =
        *(para.GetParamDouble("Cam" +  oss.str() + "_RelPosY"));
    } else {
      myMap["relPosY"] =
        *(para.AddParamDouble("Cam" + oss.str() + "_RelPosY",
                              "relative tranlation (Y component)"
                              "of camera " + oss.str(),
                              0.0, 0.0, DBL_MAX, 0, grp));
    }

    //Z component
    if ( para.CheckParam("Cam" +  oss.str() + "_RelPosZ") ){
      myMap["relPosZ"] =
        *(para.GetParamDouble("Cam" +  oss.str() + "_RelPosZ"));
    } else {
      myMap["relPosZ"] =
        *(para.AddParamDouble("Cam" + oss.str() + "_RelPosZ",
                              "relative tranlation (Z component)"
                              "of camera " + oss.str(),
                              0.0, 0.0, DBL_MAX, 0, grp));
    }

    //rotation angle X
    if ( para.CheckParam("Cam" +  oss.str() + "_RelRotX") ){
      myMap["relRotX"] =
        *(para.GetParamDouble("Cam" +  oss.str() + "_RelRotX"));
    } else {
      myMap["relRotX"] =
        *(para.AddParamDouble("Cam" + oss.str() + "_RelRotX",
                              "relative rotation (rad) (X component)"
                              "of camera " + oss.str(),
                              0.0, 0.0, DBL_MAX, 0, grp));
    }

    //rotation angle Y
    if ( para.CheckParam("Cam" +  oss.str() + "_RelRotY") ){
      myMap["relRotY"] =
        *(para.GetParamDouble("Cam" +  oss.str() + "_RelRotY"));
    } else {
      myMap["relRotY"] =
        *(para.AddParamDouble("Cam" + oss.str() + "_RelRotY",
                              "relative rotation (rad) (Y component)"
                              "of camera " + oss.str(),
                              0.0, 0.0, DBL_MAX, 0, grp));
    }

    //rotation angle Z
    if ( para.CheckParam("Cam" +  oss.str() + "_RelRotZ") ){
      myMap["relRotZ"] =
        *(para.GetParamDouble("Cam" +  oss.str() + "_RelRotZ"));
    } else {
      myMap["relRotZ"] =
        *(para.AddParamDouble("Cam" + oss.str() + "_RelRotZ",
                              "relative rotation (rad) (Z component)"
                              "of camera " + oss.str(),
                              0.0, 0.0, DBL_MAX, 0, grp));
    }

    SlaveCamsRelative_.push_back(myMap);
    oss.str(""); //clear the stream

  } //for each slave camera

  if (para.IsUsedGroupID(grp))
    para.SetGroupName(grp, "slave camera values");

} //end of _AddParameter()