1 /*=========================================================================
4 Module: $RCSfile: gdcmFile.cxx,v $
6 Date: $Date: 2004/10/20 14:30:40 $
7 Version: $Revision: 1.146 $
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 "gdcmDebug.h"
24 typedef std::pair<TagDocEntryHT::iterator,TagDocEntryHT::iterator> IterHT;
26 //-------------------------------------------------------------------------
27 // Constructor / Destructor
29 * \brief Constructor dedicated to deal with the *pixels* area of a ACR/DICOMV3
30 * file (Header only deals with the ... header)
31 * Opens (in read only and when possible) an existing file and checks
32 * for DICOM compliance. Returns NULL on failure.
33 * It will be up to the user to load the pixels into memory
34 * (see GetImageData, GetImageDataRaw)
35 * \note the in-memory representation of all available tags found in
36 * the DICOM header is post-poned to first header information access.
37 * This avoid a double parsing of public part of the header when
38 * user sets an a posteriori shadow dictionary (efficiency can be
39 * seen as a side effect).
40 * @param header already built Header
42 File::File(Header *header)
44 HeaderInternal = header;
50 * \brief Constructor dedicated to deal with the *pixels* area of a ACR/DICOMV3
51 * file (Header only deals with the ... header)
52 * Opens (in read only and when possible) an existing file and checks
53 * for DICOM compliance. Returns NULL on failure.
54 * It will be up to the user to load the pixels into memory
55 * (see GetImageData, GetImageDataRaw)
56 * \note the in-memory representation of all available tags found in
57 * the DICOM header is post-poned to first header information access.
58 * This avoid a double parsing of public part of the header when
59 * one sets an a posteriori shadow dictionary (efficiency can be
60 * seen as a side effect).
61 * @param filename file to be opened for parsing
63 File::File(std::string const & filename )
65 HeaderInternal = new Header( filename );
71 * \brief Factorization for various forms of constructors.
73 void File::Initialise()
75 if ( HeaderInternal->IsReadable() )
77 ImageDataSizeRaw = ComputeDecompressedPixelDataSizeFromHeader();
78 if ( HeaderInternal->HasLUT() )
80 ImageDataSize = 3 * ImageDataSizeRaw;
84 ImageDataSize = ImageDataSizeRaw;
87 PixelConverter = new PixelConvert;
88 PixelConverter->GrabInformationsFromHeader( HeaderInternal );
94 * \brief canonical destructor
95 * \note If the Header was created by the File constructor,
96 * it is destroyed by the File
102 delete HeaderInternal;
106 DeleteInitialValues();
110 * \brief Sets some initial values for the Constructor
111 * \warning not end user intended
113 void File::SaveInitialValues()
116 PixelRead = -1; // no ImageData read yet.
117 LastAllocatedPixelDataLength = 0;
122 InitialPlanConfig = "";
123 InitialBitsAllocated = "";
126 InitialRedLUTDescr = 0;
127 InitialGreenLUTDescr = 0;
128 InitialBlueLUTDescr = 0;
129 InitialRedLUTData = 0;
130 InitialGreenLUTData = 0;
131 InitialBlueLUTData = 0;
133 if ( HeaderInternal->IsReadable() )
135 // the following values *may* be modified
136 // by File::GetImageDataIntoVectorRaw
137 // we save their initial value.
138 InitialSpp = HeaderInternal->GetEntryByNumber(0x0028,0x0002);
139 InitialPhotInt = HeaderInternal->GetEntryByNumber(0x0028,0x0004);
140 InitialPlanConfig = HeaderInternal->GetEntryByNumber(0x0028,0x0006);
142 InitialBitsAllocated = HeaderInternal->GetEntryByNumber(0x0028,0x0100);
143 InitialHighBit = HeaderInternal->GetEntryByNumber(0x0028,0x0102);
145 // the following entries *may* be removed from the H table
146 // (NOT deleted ...) by File::GetImageDataIntoVectorRaw
147 // we keep a pointer on them.
148 InitialRedLUTDescr = HeaderInternal->GetDocEntryByNumber(0x0028,0x1101);
149 InitialGreenLUTDescr = HeaderInternal->GetDocEntryByNumber(0x0028,0x1102);
150 InitialBlueLUTDescr = HeaderInternal->GetDocEntryByNumber(0x0028,0x1103);
152 InitialRedLUTData = HeaderInternal->GetDocEntryByNumber(0x0028,0x1201);
153 InitialGreenLUTData = HeaderInternal->GetDocEntryByNumber(0x0028,0x1202);
154 InitialBlueLUTData = HeaderInternal->GetDocEntryByNumber(0x0028,0x1203);
159 * \brief restores some initial values
160 * \warning not end user intended
162 void File::RestoreInitialValues()
164 if ( HeaderInternal->IsReadable() )
166 // the following values *may* have been modified
167 // by File::GetImageDataIntoVectorRaw
168 // we restore their initial value.
169 if ( InitialSpp != "")
170 HeaderInternal->SetEntryByNumber(InitialSpp,0x0028,0x0002);
171 if ( InitialPhotInt != "")
172 HeaderInternal->SetEntryByNumber(InitialPhotInt,0x0028,0x0004);
173 if ( InitialPlanConfig != "")
175 HeaderInternal->SetEntryByNumber(InitialPlanConfig,0x0028,0x0006);
176 if ( InitialBitsAllocated != "")
177 HeaderInternal->SetEntryByNumber(InitialBitsAllocated,0x0028,0x0100);
178 if ( InitialHighBit != "")
179 HeaderInternal->SetEntryByNumber(InitialHighBit,0x0028,0x0102);
181 // the following entries *may* be have been removed from the H table
182 // (NOT deleted ...) by File::GetImageDataIntoVectorRaw
185 if (InitialRedLUTDescr)
186 HeaderInternal->AddEntry(InitialRedLUTDescr);
187 if (InitialGreenLUTDescr)
188 HeaderInternal->AddEntry(InitialGreenLUTDescr);
189 if (InitialBlueLUTDescr)
190 HeaderInternal->AddEntry(InitialBlueLUTDescr);
192 if (InitialRedLUTData)
193 HeaderInternal->AddEntry(InitialBlueLUTDescr);
194 if (InitialGreenLUTData)
195 HeaderInternal->AddEntry(InitialGreenLUTData);
196 if (InitialBlueLUTData)
197 HeaderInternal->AddEntry(InitialBlueLUTData);
202 * \brief delete initial values (il they were saved)
203 * of InitialLutDescriptors and InitialLutData
205 void File::DeleteInitialValues()
208 // InitialLutDescriptors and InitialLutData
209 // will have to be deleted if the don't belong any longer
210 // to the Header H table when the header is deleted...
212 if ( InitialRedLUTDescr )
213 delete InitialRedLUTDescr;
215 if ( InitialGreenLUTDescr )
216 delete InitialGreenLUTDescr;
218 if ( InitialBlueLUTDescr )
219 delete InitialBlueLUTDescr;
221 if ( InitialRedLUTData )
222 delete InitialRedLUTData;
224 if ( InitialGreenLUTData != NULL)
225 delete InitialGreenLUTData;
227 if ( InitialBlueLUTData != NULL)
228 delete InitialBlueLUTData;
231 //-----------------------------------------------------------------------------
234 //-----------------------------------------------------------------------------
238 * \brief computes the length (in bytes) we must ALLOCATE to receive the
239 * image(s) pixels (multiframes taken into account)
240 * \warning : it is NOT the group 7FE0 length
241 * (no interest for compressed images).
243 int File::ComputeDecompressedPixelDataSizeFromHeader()
245 // see PS 3.3-2003 : C.7.6.3.2.1
255 // YBR_FULL_422 (no LUT, no Palette)
261 // ex : gdcm-US-ALOKA-16.dcm
262 // 0028|1221 [OW] [Segmented Red Palette Color Lookup Table Data]
263 // 0028|1222 [OW] [Segmented Green Palette Color Lookup Table Data]
264 // 0028|1223 [OW] [Segmented Blue Palette Color Lookup Table Data]
266 // ex : OT-PAL-8-face.dcm
267 // 0028|1201 [US] [Red Palette Color Lookup Table Data]
268 // 0028|1202 [US] [Green Palette Color Lookup Table Data]
269 // 0028|1203 [US] [Blue Palette Color Lookup Table Data]
271 int numberBitsAllocated = HeaderInternal->GetBitsAllocated();
272 // Number of "Bits Allocated" is fixed to 16 when:
273 // - it is not defined (i.e. it's value is 0)
274 // - it's 12, since we will expand the image to 16 bits (see
275 // PixelConvert::ConvertDecompress12BitsTo16Bits() )
276 if ( ( numberBitsAllocated == 0 ) || ( numberBitsAllocated == 12 ) )
278 numberBitsAllocated = 16;
281 int DecompressedSize = HeaderInternal->GetXSize()
282 * HeaderInternal->GetYSize()
283 * HeaderInternal->GetZSize()
284 * ( numberBitsAllocated / 8 )
285 * HeaderInternal->GetSamplesPerPixel();
287 return DecompressedSize;
291 * \brief - Allocates necessary memory,
292 * - Reads the pixels from disk (uncompress if necessary),
293 * - Transforms YBR pixels, if any, into RGB pixels
294 * - Transforms 3 planes R, G, B, if any, into a single RGB Plane
295 * - Transforms single Grey plane + 3 Palettes into a RGB Plane
296 * - Copies the pixel data (image[s]/volume[s]) to newly allocated zone.
297 * @return Pointer to newly allocated pixel data.
298 * NULL if alloc fails
300 uint8_t* File::GetImageData()
303 // I need to deallocate Pixel_Data before doing any allocation:
306 if ( LastAllocatedPixelDataLength != ImageDataSize )
309 Pixel_Data = new uint8_t[ImageDataSize];
313 LastAllocatedPixelDataLength = ImageDataSize;
315 // we load the pixels (and transform grey level + LUT into RGB)
316 GetImageDataIntoVector(Pixel_Data, ImageDataSize);
318 // We say the value *is* loaded.
319 GetHeader()->SetEntryByNumber( GDCM_BINLOADED,
320 GetHeader()->GetGrPixel(), GetHeader()->GetNumPixel());
322 // Will be 7fe0, 0010 in standard case
323 GetHeader()->SetEntryBinAreaByNumber( Pixel_Data,
324 GetHeader()->GetGrPixel(), GetHeader()->GetNumPixel());
326 PixelRead = 0; // no PixelRaw
333 * Read the pixels from disk (uncompress if necessary),
334 * Transforms YBR pixels, if any, into RGB pixels
335 * Transforms 3 planes R, G, B, if any, into a single RGB Plane
336 * Transforms single Grey plane + 3 Palettes into a RGB Plane
337 * Copies at most MaxSize bytes of pixel data to caller allocated
339 * \warning This function allows people that want to build a volume
340 * from an image stack *not to* have, first to get the image pixels,
341 * and then move them to the volume area.
342 * It's absolutely useless for any VTK user since vtk chooses
343 * to invert the lines of an image, that is the last line comes first
344 * (for some axis related reasons?). Hence he will have
345 * to load the image line by line, starting from the end.
346 * VTK users have to call GetImageData
348 * @param destination Address (in caller's memory space) at which the
349 * pixel data should be copied
350 * @param maxSize Maximum number of bytes to be copied. When MaxSize
351 * is not sufficient to hold the pixel data the copy is not
352 * executed (i.e. no partial copy).
353 * @return On success, the number of bytes actually copied. Zero on
354 * failure e.g. MaxSize is lower than necessary.
356 size_t File::GetImageDataIntoVector (void* destination, size_t maxSize)
358 GetImageDataIntoVectorRaw (destination, maxSize);
359 PixelRead = 0 ; // =0 : no ImageDataRaw
360 if ( !HeaderInternal->HasLUT() )
362 return ImageDataSize;
365 FILE* fp = HeaderInternal->OpenFile();
366 if ( PixelConverter->BuildRGBImage( fp ) )
368 memmove( destination,
369 (void*)PixelConverter->GetRGB(),
370 PixelConverter->GetRGBSize() );
372 // now, it's an RGB image
373 // Lets's write it in the Header
375 // FIXME : Better use CreateOrReplaceIfExist ?
377 std::string spp = "3"; // Samples Per Pixel
378 HeaderInternal->SetEntryByNumber(spp,0x0028,0x0002);
379 std::string rgb = "RGB "; // Photometric Interpretation
380 HeaderInternal->SetEntryByNumber(rgb,0x0028,0x0004);
381 std::string planConfig = "0"; // Planar Configuration
382 HeaderInternal->SetEntryByNumber(planConfig,0x0028,0x0006);
387 // PixelConverter->BuildRGBImage() failed probably because
388 // PixelConverter->GetLUTRGBA() failed:
389 // (gdcm-US-ALOKA-16.dcm), contains Segmented xxx Palette Color
390 // that are *more* than 65535 long ?!?
391 // No idea how to manage such an image !
392 // Need to make RGB Pixels (?) from grey Pixels (?!) and Gray Lut (!?!)
393 // It seems that *no Dicom Viewer* has any idea :-(
395 std::string photomInterp = "MONOCHROME1 "; // Photometric Interpretation
396 HeaderInternal->SetEntryByNumber(photomInterp,0x0028,0x0004);
398 HeaderInternal->CloseFile();
400 /// \todo Drop Palette Color out of the Header?
401 return ImageDataSize;
405 * \brief Allocates necessary memory,
406 * Transforms YBR pixels (if any) into RGB pixels
407 * Transforms 3 planes R, G, B (if any) into a single RGB Plane
408 * Copies the pixel data (image[s]/volume[s]) to newly allocated zone.
409 * DOES NOT transform Grey plane + 3 Palettes into a RGB Plane
410 * @return Pointer to newly allocated pixel data.
411 * \ NULL if alloc fails
413 uint8_t* File::GetImageDataRaw ()
416 if ( HeaderInternal->HasLUT() )
417 /// \todo Let Header user a chance to get the right value
418 imgDataSize = ImageDataSizeRaw;
420 imgDataSize = ImageDataSize;
423 // I need to deallocate Pixel_Data before doing any allocation:
426 if ( LastAllocatedPixelDataLength != imgDataSize )
429 Pixel_Data = new uint8_t[imgDataSize];
433 LastAllocatedPixelDataLength = imgDataSize;
435 // we load the pixels ( grey level or RGB, but NO transformation)
436 GetImageDataIntoVectorRaw(Pixel_Data, imgDataSize);
438 // We say the value *is* loaded.
439 GetHeader()->SetEntryByNumber( GDCM_BINLOADED,
440 GetHeader()->GetGrPixel(), GetHeader()->GetNumPixel());
442 // will be 7fe0, 0010 in standard cases
443 GetHeader()->SetEntryBinAreaByNumber(Pixel_Data,
444 GetHeader()->GetGrPixel(), GetHeader()->GetNumPixel());
446 PixelRead = 1; // PixelRaw
452 * \brief Copies at most MaxSize bytes of pixel data to caller's
454 * \warning This function was designed to avoid people that want to build
455 * a volume from an image stack to need first to get the image pixels
456 * and then move them to the volume area.
457 * It's absolutely useless for any VTK user since vtk chooses
458 * to invert the lines of an image, that is the last line comes first
459 * (for some axis related reasons?). Hence he will have
460 * to load the image line by line, starting from the end.
461 * VTK users hace to call GetImageData
462 * \warning DOES NOT transform the Grey Plane + Palette Color (if any)
463 * into a single RGB Pixels Plane
464 * the (VTK) user will manage the palettes
466 * @param destination Address (in caller's memory space) at which the
467 * pixel data should be copied
468 * @param maxSize Maximum number of bytes to be copied. When MaxSize
469 * is not sufficient to hold the pixel data the copy is not
470 * executed (i.e. no partial copy).
471 * @return On success, the number of bytes actually copied. Zero on
472 * failure e.g. MaxSize is lower than necessary.
474 void File::GetImageDataIntoVectorRaw (void* destination, size_t maxSize)
476 // we save the initial values of the following
477 // in order to be able to restore the header in a disk-consistent state
478 // (if user asks twice to get the pixels from disk)
480 if ( PixelRead != -1 ) // File was "read" before
482 RestoreInitialValues();
485 PixelRead = 1 ; // PixelRaw
487 if ( ImageDataSize > maxSize )
489 dbg.Verbose(0, "File::GetImageDataIntoVector: pixel data bigger"
490 "than caller's expected MaxSize");
494 FILE* fp = HeaderInternal->OpenFile();
495 PixelConverter->ReadAndDecompressPixelData( fp );
496 HeaderInternal->CloseFile();
497 memmove( destination,
498 (void*)PixelConverter->GetDecompressed(),
499 PixelConverter->GetDecompressedSize() );
501 if ( ! PixelConverter->IsDecompressedRGB() )
506 ///////////////////////////////////////////////////
507 // now, it's an RGB image
508 // Lets's write it in the Header
510 // Droping Palette Color out of the Header
511 // has been moved to the Write process.
513 // TODO : move 'values' modification to the write process
514 // : save also (in order to be able to restore)
515 // : 'high bit' -when not equal to 'bits stored' + 1
516 // : 'bits allocated', when it's equal to 12 ?!
518 std::string spp = "3"; // Samples Per Pixel
519 std::string photInt = "RGB "; // Photometric Interpretation
520 std::string planConfig = "0"; // Planar Configuration
522 HeaderInternal->SetEntryByNumber(spp,0x0028,0x0002);
523 HeaderInternal->SetEntryByNumber(photInt,0x0028,0x0004);
524 HeaderInternal->SetEntryByNumber(planConfig,0x0028,0x0006);
530 * \brief Points the internal Pixel_Data pointer to the callers inData
531 * image representation, BUT WITHOUT COPYING THE DATA.
532 * 'image' Pixels are presented as C-like 2D arrays : line per line.
533 * 'volume'Pixels are presented as C-like 3D arrays : plane per plane
534 * \warning Since the pixels are not copied, it is the caller's responsability
535 * not to deallocate it's data before gdcm uses them (e.g. with
536 * the Write() method.
537 * @param inData user supplied pixel area
538 * @param expectedSize total image size, in Bytes
542 bool File::SetImageData(uint8_t* inData, size_t expectedSize)
544 HeaderInternal->SetImageDataSize( expectedSize );
545 // FIXME : if already allocated, memory leak !
547 ImageDataSize = ImageDataSizeRaw = expectedSize;
549 // FIXME : 7fe0, 0010 IS NOT set ...
554 * \brief Writes on disk A SINGLE Dicom file
555 * NO test is performed on processor "Endiannity".
556 * It's up to the user to call his Reader properly
557 * @param fileName name of the file to be created
558 * (any already existing file is over written)
559 * @return false if write fails
562 bool File::WriteRawData(std::string const & fileName)
564 FILE* fp1 = fopen(fileName.c_str(), "wb");
567 printf("Fail to open (write) file [%s] \n", fileName.c_str());
570 fwrite (Pixel_Data, ImageDataSize, 1, fp1);
577 * \brief Writes on disk A SINGLE Dicom file,
578 * using the Implicit Value Representation convention
579 * NO test is performed on processor "Endiannity".
580 * @param fileName name of the file to be created
581 * (any already existing file is overwritten)
582 * @return false if write fails
585 bool File::WriteDcmImplVR (std::string const & fileName)
587 return WriteBase(fileName, ImplicitVR);
591 * \brief Writes on disk A SINGLE Dicom file,
592 * using the Explicit Value Representation convention
593 * NO test is performed on processor "Endiannity". * @param fileName name of the file to be created
594 * (any already existing file is overwritten)
595 * @return false if write fails
598 bool File::WriteDcmExplVR (std::string const & fileName)
600 return WriteBase(fileName, ExplicitVR);
604 * \brief Writes on disk A SINGLE Dicom file,
605 * using the ACR-NEMA convention
606 * NO test is performed on processor "Endiannity".
607 * (a l'attention des logiciels cliniques
608 * qui ne prennent en entrée QUE des images ACR ...
609 * \warning if a DICOM_V3 header is supplied,
610 * groups < 0x0008 and shadow groups are ignored
611 * \warning NO TEST is performed on processor "Endiannity".
612 * @param fileName name of the file to be created
613 * (any already existing file is overwritten)
614 * @return false if write fails
617 bool File::WriteAcr (std::string const & fileName)
619 return WriteBase(fileName, ACR);
622 //-----------------------------------------------------------------------------
625 * \brief NOT a end user inteded function
626 * (used by WriteDcmExplVR, WriteDcmImplVR, WriteAcr, etc)
627 * @param fileName name of the file to be created
628 * (any already existing file is overwritten)
629 * @param type file type (ExplicitVR, ImplicitVR, ...)
630 * @return false if write fails
632 bool File::WriteBase (std::string const & fileName, FileType type)
634 if ( PixelRead == -1 && type != ExplicitVR)
639 FILE* fp1 = fopen(fileName.c_str(), "wb");
642 printf("Failed to open (write) File [%s] \n", fileName.c_str());
646 if ( type == ImplicitVR || type == ExplicitVR )
648 // writing Dicom File Preamble
649 uint8_t* filePreamble = new uint8_t[128];
650 memset(filePreamble, 0, 128);
651 fwrite(filePreamble, 128, 1, fp1);
652 fwrite("DICM", 4, 1, fp1);
654 delete[] filePreamble;
657 // --------------------------------------------------------------
658 // Special Patch to allow gdcm to re-write ACR-LibIDO formated images
660 // if recognition code tells us we dealt with a LibIDO image
661 // we reproduce on disk the switch between lineNumber and columnNumber
662 // just before writting ...
664 /// \todo the best trick would be *change* the recognition code
665 /// but pb expected if user deals with, e.g. COMPLEX images
667 std::string rows, columns;
668 if ( HeaderInternal->GetFileType() == ACR_LIBIDO)
670 rows = HeaderInternal->GetEntryByNumber(0x0028, 0x0010);
671 columns = HeaderInternal->GetEntryByNumber(0x0028, 0x0011);
673 HeaderInternal->SetEntryByNumber(columns, 0x0028, 0x0010);
674 HeaderInternal->SetEntryByNumber(rows , 0x0028, 0x0011);
676 // ----------------- End of Special Patch ----------------
678 uint16_t grPixel = HeaderInternal->GetGrPixel();
679 uint16_t numPixel = HeaderInternal->GetNumPixel();;
681 DocEntry* PixelElement =
682 GetHeader()->GetDocEntryByNumber(grPixel, numPixel);
684 if ( PixelRead == 1 )
686 // we read pixel 'as is' (no tranformation LUT -> RGB)
687 PixelElement->SetLength( ImageDataSizeRaw );
689 else if ( PixelRead == 0 )
691 // we tranformed GrayLevel pixels + LUT into RGB Pixel
692 PixelElement->SetLength( ImageDataSize );
695 HeaderInternal->Write(fp1, type);
697 // --------------------------------------------------------------
698 // Special Patch to allow gdcm to re-write ACR-LibIDO formated images
700 // ...and we restore the Header to be Dicom Compliant again
701 // just after writting
703 if ( HeaderInternal->GetFileType() == ACR_LIBIDO )
705 HeaderInternal->SetEntryByNumber(rows , 0x0028, 0x0010);
706 HeaderInternal->SetEntryByNumber(columns, 0x0028, 0x0011);
708 // ----------------- End of Special Patch ----------------
710 // fwrite(Pixel_Data, ImageDataSize, 1, fp1); // should be useless, now
717 * \brief Access to the underlying \ref PixelConverter RGBA LUT
719 uint8_t* File::GetLutRGBA()
721 return PixelConverter->GetLutRGBA();
724 } // end namespace gdcm