X-Git-Url: https://git.creatis.insa-lyon.fr/pubgit/?a=blobdiff_plain;ds=sidebyside;f=Doc%2FWebsite%2FNews.html;h=3e98d7236b9281c70dc92405d12a45dd31a01e4b;hb=8bcc29f4b38b0a81e6ca731248b8d41b4606984d;hp=66b07c3b790c6f6f33c9fad65a3f9c0c4fb3a1e2;hpb=1508b5e56dbad1df02a1983d867f1aa015a204f8;p=gdcm.git diff --git a/Doc/Website/News.html b/Doc/Website/News.html index 66b07c3b..3e98d723 100644 --- a/Doc/Website/News.html +++ b/Doc/Website/News.html @@ -8,10 +8,10 @@ - +

Gdcm News

- +

@@ -24,16 +24,26 @@ Any contribution is welcome.

Decoders
- gdcm doesn't read yet JPEG-LS and JPEG2000 encoded files. -
- gdcm doesn't read yet MPEG encoded files. +
- gdcm doesn't read yet JPEG-LS encoded files. +
  +
- gdcm doesn't read yet MPEG2 encoded files. +
-
Reader +
Reader
- Allow user to tell gdcm::Document constructor he just wants to load a given list of DocEntries (to save CPU time and RAM space) -
- Allow 'frame by frame' reading (should be helpfull for huge multiframe -images) +
- Allow 'frame by frame' reading (should be helpfull for huge + multiframe images) +
- Allow subvolume selection / frames selection before reading.
- Expose Read/Decompression mechanisms to allow user getting information from DICOMDIR
  -or from his own Data Base- and reading his images without parsing @@ -41,29 +51,29 @@ images)
Writer
- Allow user to tell the Writer he doesn't want to write down - SeqEntry (if any) -
- Allow user to tell the Writer he doesn't want to write down - Shadow groups (if any) -
- Allow user to tell the Writer which compression mode he wants
  - (Right now, no one is available) +
- Allow user to tell the Writer he wants to split a + Multiframe image into a serie of + Single frame images. +
- Allow user to tell the Writer he wants to agregate a + Serie of Single frame images into a + Multiframe image.
Reader / Writer
- Full Icon Image management (Read and Write)
- Full Overlays management (Read and Write)
  both for 'ACR-NEMA style' (using groups 0x6000 - and nexts) and 'DICOM V3 style' (using Sequences) + and next) and 'DICOM V3 style' (using Sequences)
DICOMDIR
- DICOMDIR full management (not limited to PATIENT/STUDY/SERIE/IMAGE)
- Allow user to add an entry (belonging to the file header Dicom - entries)to the default entry list, before + entries) to the default entry list, before making a DICOMDIR from a root directory -
- Allow user to add an entry of his owns (for instance an Icon - to each image, or to each Serie. +
- Allow user to add an entry of his own (for instance an Icon + to each image, or to each Serie).
SerieHelper
- Current Version + Current Version (CVS) : gdcm1.3.2
- Missing Features +
- Differences between gdcm 1.3.1 and gdcm 1.3.2 +
  - Uncorrect reading/writting of JPEG/JPE2000 images when + BitsAllocated=16/BitsStored=8 +
  - Uncorrect writing of JPEG/JPE2000 image with an 'Icon' Sequence +
  - Uncorrect writting of JPE2000 multiframe images +
  - Uncorrect writting of images with a DataElement belonging to group + 0002, inside a Sequence +
  - Uncorrect re-writting of Implicit Value Representation images with + 'shadow groups' when Explicit Value Representation was asked + (unexpected swap to Implicit VR) +
  + If you experience troubles with gdcm-written images, check which + gdcm version was used (PrintFile filein=yourFileName.dcm) +
- State of the art
  - - gdcm UML Class Diagram current version. + gdcm UML Class Diagram current version. +
  - User Documentation +
  - Developper + Documentation +
  - New Features + +
    - To be able to use gdcm1.3.x and ITK, developer is now allowed to + choose his own namespace for gdcm at CMake time : see GDCM_NAME_SPACE + option. +
    - JPEG and JPEG2000 compression writting are now available. + see Examples/WriteDicomAsJPEG.cxx and Examples/WriteDicomAsJPEG2000.cxx +
    - To try to make gdcm images PACS usable, user is now allowed to + gdcm what kind of image he wants to write, using :
      + void FileHelper::SetContentType (ImageContentType c);
      + Four different types are identifyed (probabely more will be added) : +
      - + 1) user created ex nihilo his own image and wants to write it as a Dicom image.
        + c : USER_OWN_IMAGE +
      - + 2) user modified the pixels of an existing image, using mathematical operations.
        + c : FILTERED_IMAGE +
      - + 3) user created a new image, using existing images (eg MIP, MPR, cartography image)
        + c : CREATED_IMAGE +
      - + 4) user modified/added some tags *without processing* the pixels (anonymization, etc)
        + c : UNMODIFIED_PIXELS_IMAGE +
      +
    - Stupid difference between gdcm::ValEntry + and gdcm::BinEntry removed.
      + Only gdcm::DataEntry exist, now. + Should have been considered as a 'Bug Fix'.
      + Actually, it's an API breaking modification ... +
      - + std::string const &DataEntry::GetString() const
        + returns as a string (when possible) the value of the DataEntry +
      - + void DataEntry::SetString(std::string const &value)
        + Sets the 'value' of a DataEntry, passed as a std::string +
      - + void DataEntry::SetBinArea( uint8_t *area, bool self )
        + Sets the value (non string) of the current Dicom DataEntry +
      - + void DataEntry::CopyBinArea( uint8_t *area, uint32_t length )
        + Inserts the value (non string) into the current DataEntry +
      - + void DataEntry::SetValue(const uint32_t &id, const double + &val)
        + Inserts the elementary (non string) value into the current + (multivaluated) DataEntry, at the id> position. +
      - + double DataEntry::GetValue(const uint32_t &id) const
        + returns, as a double one of the values (when entry is + multivaluated), identified by its index id. +
      +
    - + DocEntrySet::GetEntryValue() replaced by + DocEntrySet::GetEntryString()
      +
    - SerieHelper :
      + Add some methods, to split a 'SingleSerieUID' Fileset into + 'Extra Coherent' FileSets.
      + They return a std::map of 'Filesets' (actually : std::vector + of gdcm::File*)
      + The key is the 'Orientation', the 'Position' + or the value of a user choosen 'Tag'
      + - XCoherentFileSetmap SplitOnOrientation(FileList *fileSet); +
      + - XCoherentFileSetmap SplitOnPosition(FileList *fileSet); +
      + - XCoherentFileSetmap SplitOnTagValue(FileList *fileSet, + uint16_t group, uint16_t element); +
      + These methods must be called by user, depending on what he wants + to do, at application time.- *he* only knows what his Series + contain !- +
    - To avoid memory leaks and seg faults the user intended classes + use now a Reference Counter.
      +
      - new() and delete() are replaced by + New() and Delete() +
      - Register() and Unregister() methods are + available. +
      - --> Well ... People from ITK don't seem to agree too much with + that feature.
        + They demand to be allowed to allocate gdcm objects in the stack as + well, not only in the heap. +
      +
    - +
    + +
  - API breaking modifications (since previous version) +
    - Stupid difference between gdcm::ValEntry + and gdcm::BinEntry removed.
      + Only gdcm::DataEntry exist, now.
      +
```
+   ValEntry(DictEntry *e);
+   BinEntry(DictEntry *e);
+-->DataEntry *New(uint16_t group,uint16_t elem, VRKey const &vr);
+
+   std::string const &ValEntry::GetValue() const;
+   std::string const &BinEntry::GetValue() const;
+-->std::string const &DataEntry::GetString() const;
+
+   uint8_t *BinEntry::GetBinArea();
+-->uint8_t *DataEntry::GetBinArea();
+
+   void ValEntry::SetValue(std::string const &value);
+   void BinEntry::SetValue(std::string const &value);   
+-->void DataEntry::SetString(std::string const &value);
+
+   void BinEntry::SetBinArea( uint8_t *area, bool self = true );
+-->void DataEntry::SetBinArea( uint8_t *area, bool self = true );
+
+   void ValEntry::CopyValEntry(uint16_t gr, uint16_t el);
+-->void DataEntry::CopyDataEntry(uint16_t gr, uint16_t el, VRKey const &vr);
+
```
      + +
```
+Example :
+
+old way :
+        DocEntry *p3 = item2->GetDocEntry(0x0018,0x0050);
+        if( !p3 ) return false;
+        ContentEntry *entry2 = dynamic_cast(p3);
+        std::string thickness = entry2->GetValue();
+
+new way :
+        DocEntry *p3 = item2->GetDocEntry(0x0018,0x0050);
+        if( !p3 ) return false;
+        DataEntry *entry2 = dynamic_cast(p3);
+        std::string thickness = entry2->GetString();
+
+
```
      + +
    - Avoid tons of CPU time consuming accesses to DICOM Dictionnary +
```
+   DataEntry *FileHelper::CopyDataEntry(uint16_t group, uint16_t elem);
+-->DataEntry *FileHelper::CopyDataEntry(uint16_t group, uint16_t elem, 
+                                        const VRKey &vr = GDCM_VRUNKNOWN);
+
+   void FileHelper::CheckMandatoryEntry(uint16_t group, uint16_t elem, std::string value);
+-->void FileHelper::CheckMandatoryEntry(uint16_t group, uint16_t elem, std::string value,
+                                        const VRKey &vr = GDCM_VRUNKNOWN);
+      
+   void FileHelper::SetMandatoryEntry(uint16_t group, uint16_t elem, std::string value);       
+-->void FileHelper::SetMandatoryEntry(uint16_t group, uint16_t elem, std::string value,
+                                      const VRKey &vr = GDCM_VRUNKNOWN);
+
+   void FileHelper::CopyMandatoryEntry(uint16_t group, uint16_t elem, std::string value);      
+-->void FileHelper::CopyMandatoryEntry(uint16_t group, uint16_t elem, std::string value,
+                                       const VRKey &vr = GDCM_VRUNKNOWN);
+
```
      +
    - New features : +
```
+For multivaluated numeric DataEntries
+-->void DataEntry::SetValue(const uint32_t &id,const double &val);
+-->double DataEntry::GetValue(const uint32_t &id) const;
+-->uint32_t DataEntry::GetValueCount() const;
+
+For converting 'Decimal String'
+-->bool GetDSValue(std::vector <double> &valueVector);  
+
```
      + +
    - Avoid too many source file modifications from gdcm1.2 to gdcm1.3 +
```
+use :
+
+#define ValEntry                      DataEntry
+#define BinEntry                      DataEntry
+
+#define GetEntryValue(g,e)            GetEntryString(g,e)
+#define GetEntryForcedAsciiValue(g,e) GetEntryString(g,e)
+
+#define GetValEntry(g,e)              GetDataEntry(g,e)
+#define GetBinEntry(g,e)              GetDataEntry(g,e)
+#define GetValue()                    GetString()
+
+#define InsertValEntry(v,g,e,vr)      InsertEntryString(v,g,e,vr) // warning mind the VR!
+#define InsertBinEntry(b,l,g,e,vr)    InsertEntryBinArea(b,l,g,e,vr)
+
+#define SetValEntry(c,g,e)            SetEntryString(c,g,e)  | !!
+#define SetValEntry(c,en)             SetEntryString(c,en)   | !!
+
+#define SetBinEntry(c,l,en)           SetEntryBinArea(c,l,en)   | !!
+#define SetBinEntry(c,l,g,e)          SetEntryBinArea(c,l,g,e)  | !!
+
+#define NewValEntry(g,e,vr)           NewDataEntry(g,e,vr)
+#define NewBinEntry(g,e,vr)           NewDataEntry(g,e,vr)       
+
+
```
      +
    + +
  - Bug fixes +
    - Implicit VR - Big Endian (G.E Private) Transfert Syntax 16 Bits + images are now read correctly. +
    - File::GetZOrigin() returns accurate result in any case. +
    - +
    - +
    + +
  - Known Bugs +
    - Use of Implicit Value Representation writting mode may + causes troubles, when there are some SQ belonging to a + Shadow Group.
      + Better you use Explicit Value Representation writting mode ... +
    - Troubles on 'Big endian' processors (i.e. Apple/Motorola, SunSparc + ...) when writting 16 Bits images. +
    - Troubles on 64-bits processors. +
    + +
    
    +
  + + + + + + +
  +
  + + Version 1.2 +
  +
- State of the art +
  - + gdcm 1.2 UML Class Diagram version + (same as 1.1) +
  - This is the Class Diagram of the version used within ITK. + (Hope we unify CVS version and ITK version, some day!) + + +
    +
    + + Version 1.1 (September 14 2005) +
    +
  - State of the art +
    - + gdcm 1.1 UML Class Diagram version. +
    - User Documentation +
    - Developper + Documentation
    - New Features
      - Both vtkgdcmViewer and vtkgdcmViewer2 - are available to allow easy displaying of single/multiframe - GreyLevel/RGB/PaletteColor images +
      - Add the methods + gdcm::Dict:AddDict(std::string fullPathPrivateDictionaryFileName) +
        and
        + gdcm::Dict::RemoveDict(std::string fullPathPrivateDictionaryFileName) +
        + to allow user to choose the 'Private Dictionary' he wants to work with. +
        + One can dream about a better API;
        + This one allow right now anybody to see very easyly if the use + of a given private dicom dictionary is of any help or not. +
        
        +
      - + PrintFile has now a new command line argument manager option :
        + dict=fullPathNamePrivateDictionaryFile
        + to allow user to see with no extra coding what differences + makes the use or not of a private Dicom Dictionary.
        + e.g. : use it as follow
        + PrintFile filein=myGEdicomFile.dcm + dict=/user/userName/gdcm/Dicts/GEMS-Advance.dic +
        
        +
      - + (Not a great one ...) + Stupid method names :
        DicomDir::WriteDicomDir() + and DicomDir::AnonymizeDicomDir()
        replaced by :
        + DicomDir::Write() + and DicomDir::Anonymize() +
        
        +
      - + void Document::AddForceLoadElement(uint16_t group, uint16_t elem); +
        + allows user to tell gdcm::Document Loader he wants + to force the loading of a given set of DocEntries, + even if their length exceeds the current + MAX_SIZE_LOAD_ELEMENT_VALUE. +
        
        +
      - + 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 *knows* how to order his files + sh->SetUserLessThanFunction(userSuppliedComparisonFunction); + // or/and + // if user wants to sort reverse order + sh->SetSortOrderToReverse(); + + // here, we suppose only the first 'Single SerieUID' Fileset is of interest + // Just iterate using sh->NextSingleSerieUIDFileSet() + // if you want to get all of them + gdcm::FileList *l = sh->GetFirstSingleSerieUIDFileSet(); + + // if user is doesn't trust too much the files with same Serie UID + if ( !sh->IsCoherent(l) ) + return; // not same sizes, or not same 'pixel type' -> stop + + sh->OrderFileList(l); // sort the list + + vtkGdcmReader *reader = vtkGdcmReader::New(); + // if user wants to modify pixel order (Mirror, TopDown, ...) + // 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 'Single SerieUID' Fileset as produced by gdcm::SerieHelper + reader->SetCoherentFileList(l); + reader->Update(); +
        + You can see a full example in vtk/vtkgdcmSerieViewer.cxx
        + e.g.
        + + vtkgdcmSerieViewer dirname=Dentist mirror
        + vtkgdcmSerieViewer dirname=Dentist reverse
        + vtkgdcmSerieViewer dirname=Dentist reverse topdown
        + +
        + +
      - vtkGdcmReader::SetUserFunction (userSuppliedFunction)
        + with :
        + void userSuppliedFunction(uint8_t *imageData, File *f);
        + allows user to reorganize the pixels of each image just after reading + it (to mirror, or topdown the image, for instance)
        + Note : uint8_t * doesn't mean it works only on 8 Bits images. +
        It's for prototyping. Feel free to cast it. +
        
        +
      - + SerieHelper::SetUserLessThanFunction(userSuppliedComparisonFunction) +
        with :
        + bool userSuppliedComparisonFunction(File *, File *);
        + allows user -when he knows more about his files than gdcm does- + to give his own comparison function. +
      - SerieHelper::SetSortOrderToReverse allows user to ask + to sort the Files reverse order. +
      - SerieHelper::AddRestriction has now a new constructor
        + AddRestriction(group, element, value, operator);
        + allows user to exclude some files from the sorting, according to + any comparison operator
        + (GDCM_EQUAL, GDCM_DIFFERENT, + GDCM_GREATER, GDCM_GREATEROREQUAL, + GDCM_LESS, GDCM_LESSOREQUAL), not only on the + equality. +
        
        +
      - AnonymizeNoLoad used with dirin=inputDirectoryName + anonymizes all the files within the given Directory. +
        + User may also choose extra elements he wants to rub out:
        + rubout=listOfElementsToRubOut
        + with listOfElementsToRubOut : group1-elem1,group2-elem2, + ... (in hexa, no space within the list ) +
        
        +
      - gdcm::SerieHelper() has a new method + void AddGdcmFile(File *header), that allows aware user to + create a 'FileList' (actually a + std::vector< File* > ).
        + The FileList created this way will be the + 'first one' in the gdcm::FileHelper() (retrieve it with + FileList *GetFirstCoherentFileList() ).
        + It may be sorted using OrderFileList.
        + No 'coherence check' will be performed on this FileList + before sorting.
        + It may be passed to a vtkGdcmReader + (to avoid parsing twice the files) +
        
        +
      - vtkGdcmReader can now get the result of + gdcm::SerieHelper (to avoid parsing twice the files)
        + Proceed as follow :
        +
        + gdcmSerieHelper *sh = new gdcmSerieHelper(); + sh->SetDirectory(myImageDirectory, true); + gdcmFileList *l = s->GetFirstCoherentFileList(); + s->OrderFileList(l); + + vtkGdcmReader *gr = new vtkGdcmReader(); + gr->SetCoherentFileList(l); + gr->Update(); +
        + This works with a directory that contains only one 'Serie' + (same Serie UID for all the images).
        + If it contains more than one Serie, you'll have to loop + on the Series, using GetNextCoherentFileList();
        + It will be up to the user to delete the gdcm::File. +
        
        + See vtkgdcmSerieViewer for an example. +
        
        +
      - Both vtkgdcmViewer and vtkgdcmViewer2 + are available to allow easy displaying of single/multiframe + GreyLevel/RGB/PaletteColor images
      - DICOMDIR anonymiser (Load and Noload mode) +
        
        +
      - Because the gdcm::DicomDir::Load() method may be used + either for loading an already made DICOMDIR file or for + parsing all the dicom files with a given root directory we + syntaxically separated the operations:
        + For loading an already made DICOMDIR file, use :
        +
        + gdcm::DicomDir *d = new gdcm::DicomDir(); + d->SetFileName(fileName); + d->Load( ); +
        + + For parsing all the dicom files within a given root directory, use :
        +
        + gdcm::DicomDir *d = new gdcm::DicomDir(); + d->SetDirectoryName(dirName); + d->Load( ) +
        + + Don't use any longer old deprecated style:
        + + gdcm::DicomDir *d = new gdcm::DicomDir(); + d->SetParseDir(true); //or d->SetParseDir(false); + d->Load( fileName ); + +
      - User is now allowed to tell gdcm::Document constructor - he doesn't want to deal with SeqEntry - (every time it's possible)
        and/or he doesn't - want to deal with Shadow groups (every time it's - possible)
        - use :
        - gdcm::File *f = new gdcm::File(); - f->SetLoadMode(NO_SEQ | NO_SHADOW); - f->Load(fileName); - - instead of :
        + he doesn't want to deal with SeqEntry + (every time it's possible, i.e for 'true length' Sequences)
        + and/or he doesn't want to deal with Shadow groups + (every time it's possible i.e. when element 0x0000 + exists for this Group)
        + or he doesn't want to deal with SeqEntry that belong to a + Shadow group (every time it's possible + -'true length' Sequence-)
        + use :
        +
        + gdcm::File *f = new gdcm::File(); + f->SetLoadMode(NO_SEQ); | depending on what + f->SetLoadMode(NO_SHADOW); | you want *not* + f->SetLoadMode(NO_SEQ | NO_SHADOW);| to load from the + f->SetLoadMode(NO_SHADOWSEQ); | target file + f->SetFileName(fileName); + f->Load( ); +
        + Don't use any longer old deprecated style:
        gdcm::File *f = new gdcm::File(fileName);
        - (old style still available) - +
      - User is now allowed to tell gdcm::DicomDir constructor - he doesn't want to deal with SeqEntry - (every time it's possible)
        and/or he doesn't - want to deal with Shadow groups (every time it's - possible)
        - use :
        - gdcm::DicomDir *dcmdir = new gdcm::DicomDir( ); - dcmdir->SetParseDir(true); - dcmdir->SetLoadMode(NO_SEQ | NO_SHADOW); - dcmdir->Load(dirName); - - instead of :
        + he doesn't want to deal with SeqEntry + (every time it's possible, i.e for 'true length' Sequences)
        + and/or he doesn't want to deal with Shadow groups + (every time it's possible i.e. when element 0x0000 + exists for this Group)
        + or he doesn't want to deal with SeqEntry that belong to a + Shadow group (every time it's possible + -'true length' Sequence-)
        + when he parses all the Dicom files within a given directory.
        + use :
        +
        + gdcm::DicomDir *f = new gdcm::DicomDir(); + f->SetLoadMode(NO_SEQ); | depending on what + f->SetLoadMode(NO_SHADOW); | you want *not* + f->SetLoadMode(NO_SEQ | NO_SHADOW);| to load from the files + f->SetLoadMode(NO_SHADOWSEQ); | within the root directory + f->SetDirectoryName(rootDirectoryName); + f->Load( ); +
        + Don't use any longer old deprecated style:
        gdcm::DicomDir *dcmdir = new gdcm::DicomDir(dirName, true);
        - (old style still available) -
      - +
    - Bug fixes
      - No more trouble when the 'endianess' switches within Sequences. +
      - No more trouble with 'no length Sequences' belonging to a + Shadow Group when they are 'Implicit VR'.
      - The difference between MONOCHROME1 (low values = bright, high values = dark) and MONOCHROME2 (low values = dark, high values = bright) is now taken into account.
        It's no longer up to the user to change the pixels value
      - Writing a 'True Dicom' image after reading an ACR-NEMA image does not request any longer from the user to build up - 'manually' the Meta Elements group (Ox0002) + 'manually' the Meta Elements group (0x0002)
      - Old '24 Bits' ACR-NEMA are now correctly re-written in DICOM V3 mode.
      - Element 0x0000 of Shadow groups is always forced to be a ValEntry and its VR is forced to UL -
      - +
    - A.P.I. breaking modifications (since previous version : 1.0)
      - NEVER more API breaking modifications !!! - +
    - Known bugs
      - -
      -
    - Sample Data -
      +

Gdcm News

- Current Version + Current Version (CVS) : gdcm1.3.2

+ + Version 1.2 +

+ + Version 1.1 (September 14 2005) +