1 /*=========================================================================
4 Module: $RCSfile: gdcmFile.cxx,v $
6 Date: $Date: 2004/12/16 11:37:03 $
7 Version: $Revision: 1.178 $
9 Copyright (c) CREATIS (Centre de Recherche et d'Applications en Traitement de
10 l'Image). All rights reserved. See Doc/License.txt or
11 http://www.creatis.insa-lyon.fr/Public/Gdcm/License.html for details.
13 This software is distributed WITHOUT ANY WARRANTY; without even
14 the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
15 PURPOSE. See the above copyright notices for more information.
17 =========================================================================*/
20 #include "gdcmDocument.h"
21 #include "gdcmDebug.h"
23 #include "gdcmBinEntry.h"
24 #include "gdcmHeader.h"
25 #include "gdcmPixelReadConvert.h"
26 #include "gdcmPixelWriteConvert.h"
27 #include "gdcmDocEntryArchive.h"
33 typedef std::pair<TagDocEntryHT::iterator,TagDocEntryHT::iterator> IterHT;
35 //-------------------------------------------------------------------------
36 // Constructor / Destructor
38 * \brief Constructor dedicated to deal with the *pixels* area of a ACR/DICOMV3
39 * file (Header only deals with the ... header)
40 * Opens (in read only and when possible) an existing file and checks
41 * for DICOM compliance. Returns NULL on failure.
42 * It will be up to the user to load the pixels into memory
43 * (see GetImageData, GetImageDataRaw)
44 * \note the in-memory representation of all available tags found in
45 * the DICOM header is post-poned to first header information access.
46 * This avoid a double parsing of public part of the header when
47 * one sets an a posteriori shadow dictionary (efficiency can be
48 * seen as a side effect).
52 HeaderInternal = new Header( );
58 * \brief Constructor dedicated to deal with the *pixels* area of a ACR/DICOMV3
59 * file (Header only deals with the ... header)
60 * Opens (in read only and when possible) an existing file and checks
61 * for DICOM compliance. Returns NULL on failure.
62 * It will be up to the user to load the pixels into memory
63 * (see GetImageData, GetImageDataRaw)
64 * \note the in-memory representation of all available tags found in
65 * the DICOM header is post-poned to first header information access.
66 * This avoid a double parsing of public part of the header when
67 * user sets an a posteriori shadow dictionary (efficiency can be
68 * seen as a side effect).
69 * @param header already built Header
71 File::File(Header *header)
73 HeaderInternal = header;
79 * \brief Constructor dedicated to deal with the *pixels* area of a ACR/DICOMV3
80 * file (Header only deals with the ... header)
81 * Opens (in read only and when possible) an existing file and checks
82 * for DICOM compliance. Returns NULL on failure.
83 * It will be up to the user to load the pixels into memory
84 * (see GetImageData, GetImageDataRaw)
85 * \note the in-memory representation of all available tags found in
86 * the DICOM header is post-poned to first header information access.
87 * This avoid a double parsing of public part of the header when
88 * one sets an a posteriori shadow dictionary (efficiency can be
89 * seen as a side effect).
90 * @param filename file to be opened for parsing
92 File::File(std::string const & filename )
94 HeaderInternal = new Header( filename );
100 * \brief canonical destructor
101 * \note If the Header was created by the File constructor,
102 * it is destroyed by the File
106 if( PixelReadConverter )
108 delete PixelReadConverter;
110 if( PixelWriteConverter )
112 delete PixelWriteConverter;
121 delete HeaderInternal;
126 //-----------------------------------------------------------------------------
128 void File::Print(std::ostream &os)
130 HeaderInternal->SetPrintLevel(PrintLevel);
131 HeaderInternal->Print(os);
132 PixelReadConverter->Print(os);
135 //-----------------------------------------------------------------------------
138 * \brief Get the size of the image data
140 * If the image can be RGB (with a lut or by default), the size
141 * corresponds to the RGB image
142 * @return The image size
144 size_t File::GetImageDataSize()
146 if ( PixelWriteConverter->GetUserData() )
148 return PixelWriteConverter->GetUserDataSize();
151 return PixelReadConverter->GetRGBSize();
155 * \brief Get the size of the image data
157 * If the image can be RGB by transformation in a LUT, this
158 * transformation isn't considered
159 * @return The raw image size
161 size_t File::GetImageDataRawSize()
163 if ( PixelWriteConverter->GetUserData() )
165 return PixelWriteConverter->GetUserDataSize();
168 return PixelReadConverter->GetRawSize();
172 * \brief - Allocates necessary memory,
173 * - Reads the pixels from disk (uncompress if necessary),
174 * - Transforms YBR pixels, if any, into RGB pixels
175 * - Transforms 3 planes R, G, B, if any, into a single RGB Plane
176 * - Transforms single Grey plane + 3 Palettes into a RGB Plane
177 * - Copies the pixel data (image[s]/volume[s]) to newly allocated zone.
178 * @return Pointer to newly allocated pixel data.
179 * NULL if alloc fails
181 uint8_t* File::GetImageData()
183 if ( PixelWriteConverter->GetUserData() )
185 return PixelWriteConverter->GetUserData();
190 // If the decompression failed nothing can be done.
194 if ( HeaderInternal->HasLUT() && PixelReadConverter->BuildRGBImage() )
196 return PixelReadConverter->GetRGB();
200 // When no LUT or LUT conversion fails, return the Raw
201 return PixelReadConverter->GetRaw();
206 * \brief Allocates necessary memory,
207 * Transforms YBR pixels (if any) into RGB pixels
208 * Transforms 3 planes R, G, B (if any) into a single RGB Plane
209 * Copies the pixel data (image[s]/volume[s]) to newly allocated zone.
210 * DOES NOT transform Grey plane + 3 Palettes into a RGB Plane
211 * @return Pointer to newly allocated pixel data.
212 * \ NULL if alloc fails
214 uint8_t* File::GetImageDataRaw ()
221 * Read the pixels from disk (uncompress if necessary),
222 * Transforms YBR pixels, if any, into RGB pixels
223 * Transforms 3 planes R, G, B, if any, into a single RGB Plane
224 * Transforms single Grey plane + 3 Palettes into a RGB Plane
225 * Copies at most MaxSize bytes of pixel data to caller allocated
227 * \warning This function allows people that want to build a volume
228 * from an image stack *not to* have, first to get the image pixels,
229 * and then move them to the volume area.
230 * It's absolutely useless for any VTK user since vtk chooses
231 * to invert the lines of an image, that is the last line comes first
232 * (for some axis related reasons?). Hence he will have
233 * to load the image line by line, starting from the end.
234 * VTK users have to call GetImageData
236 * @param destination Address (in caller's memory space) at which the
237 * pixel data should be copied
238 * @param maxSize Maximum number of bytes to be copied. When MaxSize
239 * is not sufficient to hold the pixel data the copy is not
240 * executed (i.e. no partial copy).
241 * @return On success, the number of bytes actually copied. Zero on
242 * failure e.g. MaxSize is lower than necessary.
244 size_t File::GetImageDataIntoVector (void* destination, size_t maxSize)
248 // If the decompression failed nothing can be done.
252 if ( HeaderInternal->HasLUT() && PixelReadConverter->BuildRGBImage() )
254 if ( PixelReadConverter->GetRGBSize() > maxSize )
256 dbg.Verbose(0, "File::GetImageDataIntoVector: pixel data bigger"
257 "than caller's expected MaxSize");
261 (void*)PixelReadConverter->GetRGB(),
262 PixelReadConverter->GetRGBSize() );
263 return PixelReadConverter->GetRGBSize();
266 // Either no LUT conversion necessary or LUT conversion failed
267 if ( PixelReadConverter->GetRawSize() > maxSize )
269 dbg.Verbose(0, "File::GetImageDataIntoVector: pixel data bigger"
270 "than caller's expected MaxSize");
274 (void*)PixelReadConverter->GetRaw(),
275 PixelReadConverter->GetRawSize() );
276 return PixelReadConverter->GetRawSize();
280 * \brief Points the internal pointer to the callers inData
281 * image representation, BUT WITHOUT COPYING THE DATA.
282 * 'image' Pixels are presented as C-like 2D arrays : line per line.
283 * 'volume'Pixels are presented as C-like 3D arrays : plane per plane
284 * \warning Since the pixels are not copied, it is the caller's responsability
285 * not to deallocate it's data before gdcm uses them (e.g. with
286 * the Write() method.
287 * @param inData user supplied pixel area
288 * @param expectedSize total image size, in Bytes
292 void File::SetImageData(uint8_t* inData, size_t expectedSize)
294 SetUserData(inData,expectedSize);
298 * \brief Set the image datas defined by the user
299 * \warning When writting the file, this datas are get as default datas to write
301 void File::SetUserData(uint8_t* data, size_t expectedSize)
303 PixelWriteConverter->SetUserData(data,expectedSize);
307 * \brief Get the image datas defined by the user
308 * \warning When writting the file, this datas are get as default datas to write
310 uint8_t* File::GetUserData()
312 return PixelWriteConverter->GetUserData();
316 * \brief Get the image data size defined by the user
317 * \warning When writting the file, this datas are get as default datas to write
319 size_t File::GetUserDataSize()
321 return PixelWriteConverter->GetUserDataSize();
325 * \brief Get the image datas from the file.
326 * If a LUT is found, the datas are expanded to be RGB
328 uint8_t* File::GetRGBData()
330 return PixelReadConverter->GetRGB();
334 * \brief Get the image data size from the file.
335 * If a LUT is found, the datas are expanded to be RGB
337 size_t File::GetRGBDataSize()
339 return PixelReadConverter->GetRGBSize();
343 * \brief Get the image datas from the file.
344 * If a LUT is found, the datas are not expanded !
346 uint8_t* File::GetRawData()
348 return PixelReadConverter->GetRaw();
352 * \brief Get the image data size from the file.
353 * If a LUT is found, the datas are not expanded !
355 size_t File::GetRawDataSize()
357 return PixelReadConverter->GetRawSize();
361 * \brief Writes on disk A SINGLE Dicom file
362 * NO test is performed on processor "Endiannity".
363 * It's up to the user to call his Reader properly
364 * @param fileName name of the file to be created
365 * (any already existing file is over written)
366 * @return false if write fails
369 bool File::WriteRawData(std::string const & fileName)
371 std::ofstream fp1(fileName.c_str(), std::ios::out | std::ios::binary );
374 dbg.Verbose(2, "Fail to open (write) file:", fileName.c_str());
378 if(PixelWriteConverter->GetUserData())
379 fp1.write((char*)PixelWriteConverter->GetUserData(), PixelWriteConverter->GetUserDataSize());
380 else if(PixelReadConverter->GetRGB())
381 fp1.write((char*)PixelReadConverter->GetRGB(), PixelReadConverter->GetRGBSize());
382 else if(PixelReadConverter->GetRaw())
383 fp1.write((char*)PixelReadConverter->GetRaw(), PixelReadConverter->GetRawSize());
391 * \brief Writes on disk A SINGLE Dicom file,
392 * using the Implicit Value Representation convention
393 * NO test is performed on processor "Endiannity".
394 * @param fileName name of the file to be created
395 * (any already existing file is overwritten)
396 * @return false if write fails
399 bool File::WriteDcmImplVR (std::string const & fileName)
401 SetWriteTypeToDcmImplVR();
402 return Write(fileName);
406 * \brief Writes on disk A SINGLE Dicom file,
407 * using the Explicit Value Representation convention
408 * NO test is performed on processor "Endiannity". * @param fileName name of the file to be created
409 * (any already existing file is overwritten)
410 * @return false if write fails
413 bool File::WriteDcmExplVR (std::string const & fileName)
415 SetWriteTypeToDcmExplVR();
416 return Write(fileName);
420 * \brief Writes on disk A SINGLE Dicom file,
421 * using the ACR-NEMA convention
422 * NO test is performed on processor "Endiannity".
423 * (a l'attention des logiciels cliniques
424 * qui ne prennent en entrée QUE des images ACR ...
425 * \warning if a DICOM_V3 header is supplied,
426 * groups < 0x0008 and shadow groups are ignored
427 * \warning NO TEST is performed on processor "Endiannity".
428 * @param fileName name of the file to be created
429 * (any already existing file is overwritten)
430 * @return false if write fails
433 bool File::WriteAcr (std::string const & fileName)
436 return Write(fileName);
439 bool File::Write(std::string const& fileName)
441 return WriteBase(fileName);
444 bool File::SetEntryByNumber(std::string const& content,
445 uint16_t group, uint16_t element)
447 return HeaderInternal->SetEntryByNumber(content,group,element);
450 bool File::SetEntryByNumber(uint8_t* content, int lgth,
451 uint16_t group, uint16_t element)
453 return HeaderInternal->SetEntryByNumber(content,lgth,group,element);
456 bool File::ReplaceOrCreateByNumber(std::string const& content,
457 uint16_t group, uint16_t element)
459 return HeaderInternal->ReplaceOrCreateByNumber(content,group,element) != NULL;
462 bool File::ReplaceOrCreateByNumber(uint8_t* binArea, int lgth,
463 uint16_t group, uint16_t element)
465 return HeaderInternal->ReplaceOrCreateByNumber(binArea,lgth,group,element) != NULL;
469 * \brief Access to the underlying \ref PixelReadConverter RGBA LUT
471 uint8_t* File::GetLutRGBA()
473 return PixelReadConverter->GetLutRGBA();
476 //-----------------------------------------------------------------------------
479 * \brief NOT a end user inteded function
480 * (used by WriteDcmExplVR, WriteDcmImplVR, WriteAcr, etc)
481 * @param fileName name of the file to be created
482 * (any already existing file is overwritten)
483 * @param type file type (ExplicitVR, ImplicitVR, ...)
484 * @return false if write fails
486 bool File::WriteBase (std::string const & fileName)
491 SetWriteFileTypeToImplicitVR();
494 SetWriteFileTypeToExplicitVR();
498 SetWriteFileTypeToACR();
501 SetWriteFileTypeToExplicitVR();
504 // --------------------------------------------------------------
505 // Special Patch to allow gdcm to re-write ACR-LibIDO formated images
507 // if recognition code tells us we dealt with a LibIDO image
508 // we reproduce on disk the switch between lineNumber and columnNumber
509 // just before writting ...
510 /// \todo the best trick would be *change* the recognition code
511 /// but pb expected if user deals with, e.g. COMPLEX images
512 if( WriteType == ACR_LIBIDO )
518 SetWriteToNoLibido();
520 // ----------------- End of Special Patch ----------------
532 bool check = CheckWriteIntegrity();
535 check = HeaderInternal->Write(fileName,WriteType);
539 RestoreWriteFileType();
541 // --------------------------------------------------------------
542 // Special Patch to allow gdcm to re-write ACR-LibIDO formated images
544 // ...and we restore the Header to be Dicom Compliant again
545 // just after writting
546 RestoreWriteOfLibido();
547 // ----------------- End of Special Patch ----------------
553 * \brief Check the write integrity
555 * The tests made are :
556 * - verify the size of the image to write with the possible write
557 * when the user set an image data
558 * @return true if the check successfulls
560 bool File::CheckWriteIntegrity()
562 if(PixelWriteConverter->GetUserData())
564 int numberBitsAllocated = HeaderInternal->GetBitsAllocated();
565 if ( numberBitsAllocated == 0 || numberBitsAllocated == 12 )
567 numberBitsAllocated = 16;
570 size_t decSize = HeaderInternal->GetXSize()
571 * HeaderInternal->GetYSize()
572 * HeaderInternal->GetZSize()
573 * ( numberBitsAllocated / 8 )
574 * HeaderInternal->GetSamplesPerPixel();
575 size_t rgbSize = decSize;
576 if( HeaderInternal->HasLUT() )
577 rgbSize = decSize * 3;
582 if( decSize!=PixelWriteConverter->GetUserDataSize() )
584 dbg.Verbose(0, "File::CheckWriteIntegrity: Data size is incorrect (Raw)");
585 //std::cerr << "File::CheckWriteIntegrity: Data size is incorrect (Raw)\n"
586 // << decSize << " / " << PixelWriteConverter->GetUserDataSize() << "\n";
591 if( rgbSize!=PixelWriteConverter->GetUserDataSize() )
593 dbg.Verbose(0, "File::CheckWriteIntegrity: Data size is incorrect (RGB)");
594 //std::cerr << "File::CheckWriteIntegrity: Data size is incorrect (RGB)\n"
595 // << decSize << " / " << PixelWriteConverter->GetUserDataSize() << "\n";
605 void File::SetWriteToRaw()
607 if(HeaderInternal->GetNumberOfScalarComponents()==3 && !HeaderInternal->HasLUT())
613 ValEntry* photInt = CopyValEntry(0x0028,0x0004);
614 if(HeaderInternal->HasLUT())
616 photInt->SetValue("PALETTE COLOR ");
620 photInt->SetValue("MONOCHROME1 ");
623 PixelWriteConverter->SetReadData(PixelReadConverter->GetRaw(),
624 PixelReadConverter->GetRawSize());
626 BinEntry* pixel = CopyBinEntry(GetHeader()->GetGrPixel(),GetHeader()->GetNumPixel());
627 pixel->SetValue(GDCM_BINLOADED);
628 pixel->SetBinArea(PixelWriteConverter->GetData(),false);
629 pixel->SetLength(PixelWriteConverter->GetDataSize());
631 Archive->Push(photInt);
632 Archive->Push(pixel);
636 void File::SetWriteToRGB()
638 if(HeaderInternal->GetNumberOfScalarComponents()==3)
640 PixelReadConverter->BuildRGBImage();
642 ValEntry* spp = CopyValEntry(0x0028,0x0002);
645 ValEntry* planConfig = CopyValEntry(0x0028,0x0006);
646 planConfig->SetValue("0 ");
648 ValEntry* photInt = CopyValEntry(0x0028,0x0004);
649 photInt->SetValue("RGB ");
651 if(PixelReadConverter->GetRGB())
653 PixelWriteConverter->SetReadData(PixelReadConverter->GetRGB(),
654 PixelReadConverter->GetRGBSize());
658 PixelWriteConverter->SetReadData(PixelReadConverter->GetRaw(),
659 PixelReadConverter->GetRawSize());
662 BinEntry* pixel = CopyBinEntry(GetHeader()->GetGrPixel(),GetHeader()->GetNumPixel());
663 pixel->SetValue(GDCM_BINLOADED);
664 pixel->SetBinArea(PixelWriteConverter->GetData(),false);
665 pixel->SetLength(PixelWriteConverter->GetDataSize());
668 Archive->Push(planConfig);
669 Archive->Push(photInt);
670 Archive->Push(pixel);
673 Archive->Push(0x0028,0x1101);
674 Archive->Push(0x0028,0x1102);
675 Archive->Push(0x0028,0x1103);
676 Archive->Push(0x0028,0x1201);
677 Archive->Push(0x0028,0x1202);
678 Archive->Push(0x0028,0x1203);
681 // Thus, we have a RGB image and the bits allocated = 24 and
682 // samples per pixels = 1 (in the read file)
683 if(HeaderInternal->GetBitsAllocated()==24)
685 ValEntry* bitsAlloc = CopyValEntry(0x0028,0x0100);
686 bitsAlloc->SetValue("8 ");
688 ValEntry* bitsStored = CopyValEntry(0x0028,0x0101);
689 bitsStored->SetValue("8 ");
691 ValEntry* highBit = CopyValEntry(0x0028,0x0102);
692 highBit->SetValue("7 ");
694 Archive->Push(bitsAlloc);
695 Archive->Push(bitsStored);
696 Archive->Push(highBit);
705 void File::RestoreWrite()
707 Archive->Restore(0x0028,0x0002);
708 Archive->Restore(0x0028,0x0004);
709 Archive->Restore(0x0028,0x0006);
710 Archive->Restore(GetHeader()->GetGrPixel(),GetHeader()->GetNumPixel());
712 // For old ACR-NEMA (24 bits problem)
713 Archive->Restore(0x0028,0x0100);
714 Archive->Restore(0x0028,0x0101);
715 Archive->Restore(0x0028,0x0102);
718 Archive->Restore(0x0028,0x1101);
719 Archive->Restore(0x0028,0x1102);
720 Archive->Restore(0x0028,0x1103);
721 Archive->Restore(0x0028,0x1201);
722 Archive->Restore(0x0028,0x1202);
723 Archive->Restore(0x0028,0x1203);
726 void File::SetWriteFileTypeToACR()
728 Archive->Push(0x0002,0x0010);
731 void File::SetWriteFileTypeToExplicitVR()
733 std::string ts = Util::DicomString(
734 Document::GetTransferSyntaxValue(ExplicitVRLittleEndian).c_str() );
736 ValEntry* tss = CopyValEntry(0x0002,0x0010);
742 void File::SetWriteFileTypeToImplicitVR()
744 std::string ts = Util::DicomString(
745 Document::GetTransferSyntaxValue(ImplicitVRLittleEndian).c_str() );
747 ValEntry* tss = CopyValEntry(0x0002,0x0010);
753 void File::RestoreWriteFileType()
755 Archive->Restore(0x0002,0x0010);
758 void File::SetWriteToLibido()
760 ValEntry *oldRow = dynamic_cast<ValEntry *>
761 (HeaderInternal->GetDocEntryByNumber(0x0028, 0x0010));
762 ValEntry *oldCol = dynamic_cast<ValEntry *>
763 (HeaderInternal->GetDocEntryByNumber(0x0028, 0x0011));
765 if( oldRow && oldCol )
767 std::string rows, columns;
769 ValEntry *newRow=new ValEntry(oldRow->GetDictEntry());
770 ValEntry *newCol=new ValEntry(oldCol->GetDictEntry());
772 newRow->Copy(oldCol);
773 newCol->Copy(oldRow);
775 newRow->SetValue(oldCol->GetValue());
776 newCol->SetValue(oldRow->GetValue());
778 Archive->Push(newRow);
779 Archive->Push(newCol);
782 ValEntry *libidoCode = CopyValEntry(0x0008,0x0010);
783 libidoCode->SetValue("ACRNEMA_LIBIDO_1.1");
784 Archive->Push(libidoCode);
787 void File::SetWriteToNoLibido()
789 ValEntry *recCode = dynamic_cast<ValEntry *>
790 (HeaderInternal->GetDocEntryByNumber(0x0008,0x0010));
793 if( recCode->GetValue() == "ACRNEMA_LIBIDO_1.1" )
795 ValEntry *libidoCode = CopyValEntry(0x0008,0x0010);
796 libidoCode->SetValue("");
797 Archive->Push(libidoCode);
802 void File::RestoreWriteOfLibido()
804 Archive->Restore(0x0028,0x0010);
805 Archive->Restore(0x0028,0x0011);
806 Archive->Restore(0x0008,0x0010);
809 ValEntry* File::CopyValEntry(uint16_t group,uint16_t element)
811 DocEntry* oldE = HeaderInternal->GetDocEntryByNumber(group, element);
816 newE = new ValEntry(oldE->GetDictEntry());
821 newE = GetHeader()->NewValEntryByNumber(group,element);
827 BinEntry* File::CopyBinEntry(uint16_t group,uint16_t element)
829 DocEntry* oldE = HeaderInternal->GetDocEntryByNumber(group, element);
834 newE = new BinEntry(oldE->GetDictEntry());
839 newE = GetHeader()->NewBinEntryByNumber(group,element);
845 //-----------------------------------------------------------------------------
848 * \brief Factorization for various forms of constructors.
850 void File::Initialise()
852 WriteMode = WMODE_RAW;
853 WriteType = ExplicitVR;
855 PixelReadConverter = new PixelReadConvert;
856 PixelWriteConverter = new PixelWriteConvert;
857 Archive = new DocEntryArchive( HeaderInternal );
859 if ( HeaderInternal->IsReadable() )
861 PixelReadConverter->GrabInformationsFromHeader( HeaderInternal );
865 uint8_t* File::GetRaw()
867 uint8_t* raw = PixelReadConverter->GetRaw();
870 // The Raw image migth not be loaded yet:
871 std::ifstream* fp = HeaderInternal->OpenFile();
872 PixelReadConverter->ReadAndDecompressPixelData( fp );
874 HeaderInternal->CloseFile();
876 raw = PixelReadConverter->GetRaw();
879 dbg.Verbose(0, "File::GetRaw: read/decompress of "
880 "pixel data apparently went wrong.");
888 //-----------------------------------------------------------------------------
891 //-----------------------------------------------------------------------------
892 } // end namespace gdcm