+/*=========================================================================
+
+ Program: gdcm
+ Module: $RCSfile: vtkGdcmReader.cxx,v $
+ Language: C++
+ Date: $Date: 2005/07/30 18:31:25 $
+ Version: $Revision: 1.74 $
+
+ Copyright (c) CREATIS (Centre de Recherche et d'Applications en Traitement de
+ l'Image). All rights reserved. See Doc/License.txt or
+ http://www.creatis.insa-lyon.fr/Public/Gdcm/License.html for details.
+
+ This software is distributed WITHOUT ANY WARRANTY; without even
+ the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+ PURPOSE. See the above copyright notices for more information.
+
+=========================================================================*/
+
+//-----------------------------------------------------------------------------
+// //////////////////////////////////////////////////////////////
+//
+//===> Many users expect from vtkGdcmReader it 'orders' the images
+// (that's the job of gdcm::SerieHelper ...)
+// When user *knows* the files with same Serie UID
+// have same sizes, same 'pixel' type, same color convention, ...
+// the right way to proceed is as follow :
+//
+// gdcm::SerieHelper *sh= new gdcm::SerieHelper();
+// // if user wants *not* to load some parts of the file headers
+// sh->SetLoadMode(loadMode);
+// // if user wants *not* to load some files
+// sh->AddRestriction(group, element, value, operator);
+// sh->AddRestriction( ...
+// sh->SetDirectory(directoryWithImages);
+//
+// // if user wants to sort reverse order
+// sh->SetSortOrderToReverse();
+// // here, we suppose only the first Coherent File List is of interest
+// gdcm::FileList *l = sh->GetFirstCoherentFileList();
+// // if user is doesn't trust too much the files with same Serie UID
+// if ( !sh->IsCoherent(l) )
+// return; // not same sizes, same 'pixel' type -> stop
+// sh->OrderFileList(l); // sort the list
+//
+// vtkGdcmReader *reader = vtkGdcmReader::New();
+// // if user wants to modify pixel order (Mirror, TopDown, 90°Rotate, ...)
+// // he has to supply the function that does the job
+// // (a *very* simple example is given in vtkgdcmSerieViewer.cxx)
+// reader->SetUserFunction (userSuppliedFunction);
+// // to pass a 'Coherent File List' as produced by gdcm::SerieHelper
+// reader->SetCoherentFileList(l);
+// reader->Update();
+
+// WARNING TODO CLEANME
+// Actual limitations of this code
+// when a Coherent File List from SerieHelper is not used (bad idea :-(
+//
+// /////// Redundant and unnecessary header parsing
+// In it's current state this code actually parses three times the Dicom
+// header of a file before the corresponding image gets loaded in the
+// ad-hoc vtkData !
+// Here is the process:
+// 1/ First loading happens in ExecuteInformation which, in order to
+// positionate the vtk extents, calls CheckFileCoherence. The purpose
+// of CheckFileCoherence is to make sure all the images in the future
+// stack are "homogenous" (same size, same representation...).
+// This can only be achieved by parsing all the Dicom headers...
+// --> to avoid loosing too much time :
+// If user is 150% sure *all* the files are coherent, that is to say :
+// they may be open, they are gdcm-readable, they have the same sizes,
+// they have the same 'pixel' type, they are single frame,
+// they have the same color convention ...
+// he may use SetCheckFileCoherenceLight() to request a 'light' coherence
+// checking
+// 2/ ExecuteData is then responsible for the next two loadings - 2 ?!?-:
+// 2a/ ExecuteData calls AllocateOutputData that in turn seems to
+// (indirectely call) ExecuteInformation which ends up in a second
+// header parsing
+// This is fixed by adding a test at the beginning of ExecuteInformation
+// on the modification of the object instance. If a modification have been
+// made (method Modified() ), the MTime value is increased. The fileTime
+// is compared to this new value to find a modification in the class
+// parameters
+// 2b/ the core of ExecuteData then needs gdcm::File (which in turns
+// initializes gdcm::File in the constructor) in order to access
+// the data-image.
+//
+// Possible solution:
+// maintain a list of gdcm::Files (created by say ExecuteInformation) created
+// once and for all accross the life of vtkGdcmFile (it would only load
+// new gdcm::File if the user changes the list). ExecuteData would then use
+// those gdcm::File and hence avoid calling the constructor:
+// - advantage: the header of the files would only be parsed once.
+// - drawback: once execute information is called (i.e. on creation of
+// a vtkGdcmFile) the gdcm::File structure is loaded in memory.
+// The average size of a gdcm::File being of 100Ko,
+// if oneloads 10 stacks of images with say 200 images each,
+// you end-up with a loss of 200Mo...
+//
+// /////// Never unallocated memory:
+// ExecuteData allocates space for the pixel data [which will get pointed
+// by the vtkPointData() through the call
+// data->GetPointData()->GetScalars()->SetVoidArray(mem, StackNumPixels, 0);]
+// This data is never "freed" neither in the destructor nor when the
+// filename list is extended, ExecuteData is called a second (or third)
+// time...
+//
+//
+
+// //////////////////////////////////////////////////////////////
+
+#include "gdcmFileHelper.h"
+#include "gdcmFile.h"
+#include "gdcmDocument.h" // for NO_SEQ
+
+#include "vtkGdcmReader.h"
+#include "gdcmDebug.h"
+
+//#include <stdio.h>