ENH: Use display tables to allow showing derived and custom columns in DICOM browser #858

cpinter · 2019-04-09T19:42:01Z

The displayed fields are in the same tables as the raw DICOM tags, with additional fields:
- Timestamp fields for insertion and displayed field generation
- Patients: displayed patient name (human readable), number of studies
- Studies: number of series
- Series: generic "size" column, and number of images and frames
A new ColumnDisplayProperties table is added that contains the display properties for the patient, study, series tables:
- Displayed column name
- Visibility
- Weight: determines order, smaller values for columns towards the left ("heaviest sinks down")
- Format: format strings for dates and names for example (TBD)

cpinter · 2019-04-09T19:44:11Z

This is a change originally implemented (partially) at the CTK Hackfest in 2013. It has now been resurrected and finished.

It provides a more human readable (column headers, patient names, series descriptions, etc.), more usable (date added, number of studies, etc.), and more configurable DICOM browser.

This is what it looks like with the defaults in Slicer:

@pieper @jcfr @lassoan

cpinter · 2019-04-09T19:49:59Z

I plan make the changes in Slicer after this has been integrated. (Besides the CTK hash update it's just an additional Application Setting about the DICOM schema update, which I want to set to AskUser instead of the CTK default AlwaysUpdate).

pieper · 2019-04-09T20:16:08Z

Really nice!

FYI @nolden

jcfr · 2019-04-09T20:38:29Z

Libs/DICOM/Core/Resources/dicom-schema.sql

@@ -21,23 +22,44 @@ DROP INDEX IF EXISTS 'SeriesStudyIndex' ;
 DROP INDEX IF EXISTS 'StudiesPatientIndex' ;

 CREATE TABLE 'SchemaInfo' ( 'Version' VARCHAR(1024) NOT NULL );
-INSERT INTO 'SchemaInfo' VALUES('0.5.3');
+INSERT INTO 'SchemaInfo' VALUES('0.6.1');


Why 0.6.1 and not 0.6.0 ?

We used 0.6.0 in a custom application, then realized that we had to make some more changes, the result is this version, 0.6.1.

jcfr · 2019-04-09T20:50:54Z

Libs/DICOM/Core/ctkDICOMDatabase.h

@@ -199,6 +199,9 @@ class CTK_DICOM_CORE_EXPORT ctkDICOMDatabase : public QObject
                            bool createHierarchy = true,
                            const QString& destinationDirectoryName = QString() );

+  /// Update the fields in the database that are used for displaying information from information stored in the tag-cache


Would it be possible to update the docstring to describe what is a "displayed field" ?

As well as the relation ship with "weight". If this specific method is not the best place to document this, it could be added in the class documentation.

I also wonder if "displayed" is the best name.

May be "prettified" would be better or displayable (already used in the ctkDICOMDisplayedFieldGenerator classname) ?

I'm surprised that "prettify" is even a word, but apparently it is: "make (someone or something) appear superficially pretty or attractive."

I think "displayed" or "displayable" captures the intent better, which is converting from machine-readable data to text that can be displayed to the user.

think "displayed" or "displayable" captures the intent better

👍

jcfr · 2019-04-09T20:55:42Z

Libs/DICOM/Core/ctkDICOMDatabase.h

  void schemaUpdated();

+  /// Trigger showing progress dialog for display fields update
+  void displayFieldsUpdateStarted();


displayedFieldsUpdateStarted or prettifiedFieldsUpdateStarted

jcfr · 2019-04-09T21:00:29Z

Libs/DICOM/Core/ctkDICOMDisplayedFieldGenerator.h

+
+/// \ingroup DICOM_Core
+///
+/// \brief Generates displayable data fields from DICOM tags


It would be neat to describe here the role of the class was well as the relationship with the "rules" (associated with ctkDICOMDisplayedFieldGeneratorAbstractRule)

jcfr · 2019-04-09T21:01:09Z

Libs/DICOM/Core/ctkDICOMDisplayedFieldGeneratorAbstractRule.h

+
+/// \ingroup DICOM_Core
+///
+/// Abstract base class for generating displayed fields from DICOM fields


Indicate here that this class works with ctkDICOMDisplayedFieldGenerator

jcfr · 2019-04-09T21:01:46Z

Libs/DICOM/Core/ctkDICOMDisplayedFieldGeneratorRadiotherapySeriesDescriptionRule.h

+
+#define EMPTY_SERIES_DESCRIPTION_RTPLAN "Unnamed RT Plan"
+#define EMPTY_SERIES_DESCRIPTION_RTSTRUCT "Unnamed RT Structure Set"
+#define EMPTY_SERIES_DESCRIPTION_RTIMAGE "Unnamed RT Image"


instead of macro, what about defining a const field ?

jcfr · 2019-04-09T21:02:50Z

Libs/DICOM/Core/ctkDICOMItem.h

@@ -223,6 +223,7 @@ class CTK_DICOM_CORE_EXPORT ctkDICOMItem
    /// \brief Nicely formatted (group,element) version of a tag
    ///
    static QString TagKey( const DcmTag& tag );
+    static QString TagKeyStripped( const DcmTag& tag );


Is this method required ? Should TagKey be systematically stripped ?

TagKey returns the tag in parentheses. TagKeyStripped does not have the parentheses. I don't think the original one could be removed. However, maybe the name of the new function is not good enough. If you have a better suggestion let me know.

What about TagKeyWithoutParenthesis ? Or may a static function called StipParenthesis could be added ? And the same effect would be achieved doing StipParenthesis(TagKey(tag))

How about TagKeyUnpunctuated or TagKeyWitoutPunctuation and unpunctuateTagKey?

TagKeyWithoutPunctuation 👍

I like TagKeyUnpunctuated and TagKeyWithoutPunctuation. There is still a comma between the numbers. Is it punctuation? Because if it is then this name too would be somewhat misleading.
The parentheses version sounds a bit strange to me.

I would also be fine keeping TagKeyStripped, let's just make sure to add a docstring explaining what the function is doing.

Oh, if it only changes removes the parentheses and not the comma then I'd change my vote to TagKeyWithoutParenthesis but am also fine with TagKeyStripped with documentation.

Just for reference, in similar javascript code we use punctuateTag and unpunctuateTag. to go between (XXXX,XXXX), used in the dcmtk-derived data dictionary and XXXXXXXX used in DICOM JSON Model. My current thinking is that these are close to the standard which uses "tag" made of group and element, but there's no reason to change the usage in CTK at this point.

I updated the PR keeping TagStripped but with explanation. I can still change it to TagKeyWithoutParenthesis if it's better for everyone.

cpinter · 2019-04-09T23:36:36Z

Thanks for the review @jcfr ! I'll address the cmoments tomorrow.

So is there anything to do with the ...DisplayFields... functions/variables/comments?

fedorov · 2019-04-11T16:42:52Z

Few comments on the display fields:

I think "Number of images" should be renamed to "Number of instances".
Should "Study Description" and "Series Description" be used in place of "Description"?

cpinter · 2019-04-11T17:34:31Z

I think "Number of images" should be renamed to "Number of instances"

We thought about this, and decided that the average user probably won't understand what are instances, and they are almost always images

Should "Study Description" and "Series Description" be used in place of "Description"?

Both are fine with me and we can change it, but then I'd need to increase the schema version again.
What would be the advantage of using the long forms?

lassoan · 2019-04-11T18:04:51Z

The original idea of the DICOM database to strictly store only original DICOM values. This resulted in a barely usable DICOM browser with severe limitations. Due to inconsistencies and complexities of DICOM and how it is implemented in various software, the raw DICOM field values are not meaningful for users. They need to be processed, merged, interpreted for the user before displaying them.

For example, for some RT IODs, "Series description" field is always empty and a completely different field is used for storing series description. "Description" field fill rules can construct the description from fields depending on what kind of series is that, what device generated it, what other fields are specified, etc.

Similarly, we would not like to show number of instances to the user. Instead, we want to report the number of slices (regardless of a volume is stored in an enhanced format in a single file or in a legacy format in one file per slice).

So, the difference in names is not just for sake of simplification but also to indicate that it is not a 1-to-1 mapping to some DICOM field.

cpinter · 2019-04-11T18:16:16Z

regardless of a volume is stored in an enhanced format in a single file or in a legacy format in one file per slice

The current implementation actually does show the number of instances that belongs to the series, but this is one of the few things we'd like to improve later.

About the series description: that's right, if we keep the name it might suggest that it contains the SeriesDescription tag, which is not always true (which is currently in case of some RT-specific modalities).

cpinter · 2019-04-15T14:45:56Z

@fedorov @pieper Are there further concerns, e.g. about the column names discussed above?

fedorov · 2019-04-15T15:49:18Z

For example, for some RT IODs, "Series description" field is always empty and a completely different field is used for storing series description. "Description" field fill rules can construct the description from fields depending on what kind of series is that, what device generated it, what other fields are specified, etc.

Similarly, we would not like to show number of instances to the user. Instead, we want to report the number of slices (regardless of a volume is stored in an enhanced format in a single file or in a legacy format in one file per slice).

About "number of images" vs "number of instances" - I think it should be quite easy to conceptualize "instance" for the user. The advantage is that the column name would be more generic and consistent with the content of that column for a variety of series types. Considering your explanation, I agree it makes sense to deviate from direct mapping between column names and DICOM attribute names. So "instance" may not map to the "DICOM instance", but refer to the instance of "thing" being counted. For example, in RTSTRUCT - you probably would want to count contours, or structures - does it make sense to refer to either one as "image"? In SEG - you would count frames, or segments, probably not images. What would "Number of images" mean when referring to RWWM or SR modalities? I just think it is an unnecessary and confusing simplification.

EDIT: Another "neutral" name for that column could be "Count" or something of that kind.

About "series description" and "study description". Adding "Study" and "Series" for the "Description" would not imply they map one-to-one to the DICOM content, but would just make the appearance of the table more consistent. For example, you already say "Study ID", "Series #", "Number of Studies", "Number of Series" - it just looks inconsistent to drop that specification for the "Description" column.

fedorov · 2019-04-15T15:56:43Z

As I think about this, this approach of not mapping attributes one-to-one to DICOM is great if someone is using Slicer and nothing else. But I think it will be quite confusing for the users who work with different tools, as the table view they will see is likely to be very different in Slicer from other tools that (I think) just display DICOM attribute values. Did you think about this? Did you consider supporting a configuration mode for the DICOM browser that would allow to switch to the behavior consistent with non-Slicer tools?

cpinter · 2019-04-15T16:09:44Z

they will see is likely to be very different in Slicer from other tools

The current customizations of fields are only for cases where

The raw DICOM tag is not human readable (like patient name, which is probably processed in other software as well)
The raw DICOM tag is empty for certain modalities (like RT series descriptions), where the user will appreciate some information vs none

So no field is really "changed" in the DICOM browser. I don't think it will cause a problem when using different tools with this initial version.
However your point is a good one, and I agree that we should keep this in mind when extending the mechanism with new plugins, or the existing ones with new ways of processing tags.

About the column names:

I think that your explanation for study/series description fields make sense, and I'd be okay with either * The instances/images question is trickier, because if we choose instances, then the number of images in a single file volume will be off, but if we choose images, then the SEG/RTSS/etc. modalities will be off. However, as the number of instances for almost all modalities except volumes is 1 (am I mistaken?), this piece of information is only useful for volumes, which may have 1 instance, but many slices.

I'll wait until @pieper @lassoan and maybe @jcfr chime in, and then make any necessary changes if the consensus is to change these.

fedorov · 2019-04-15T16:20:55Z

The current customizations of fields are only for cases where

Right. I am just thinking about the situation where user has certain expectations about what to see in a certain field, based on viewing it in another tool DICOM table, and then they see something different (which could be much much more informative!) in Slicer ... Maybe a related suggestion is to somehow mark those fields that have been altered?

The instances/images question is trickier, because if we choose instances, then the number of images in a single file volume will be off, but if we choose images, then the SEG/RTSS/etc. modalities will be off. However, as the number of instances for almost all modalities except volumes is 1 (am I mistaken?), this piece of information is only useful for volumes, which may have 1 instance, but many slices.

By "instance" I meant a generic countable item stored in a DICOM series, which would be modality-specific. Maybe "Count" or even "#" is a better and more neutral name instead of "Number of images" or "Number of instances"? Maybe it would it be possible to show in tooltip what this number refers to for the specific series?

lassoan · 2019-04-15T16:25:21Z

I think it will be quite confusing for the users who work with different tools

I don't know any reasonably usable software that would not separate the patient browser from DICOM metadata view. Do you know any? Then we could learn from that. If anybody is interested in raw DICOM fields then the metadata browser is there.

About "number of images" vs "number of instances"

I agree that "images" term is simplification (what if it is an RTPLAN, etc.). We thought it should be acceptable, since this term has been used for example in OsiriX for many years (https://www.osirix-viewer.com/wp2015/wp-content/uploads/2015/09/Database-1024x576.png). We could use another word, but I would avoid "instance", since that would mislead users to think that it is raw DICOM value. What columns names are displayed in software that you have access to?

fedorov · 2019-04-15T16:32:31Z

I don't know any reasonably usable software that would not separate the patient browser from DICOM metadata view.

I think there is a misunderstanding on either my or your side. An example of scenario I had in mind is the following:

User views DICOM study in the DICOM browser of some software, and sees series description is set to blank for one of the series.
User then loads that same study in Slicer, and none of the series in that study is blank, as seen in the Slicer DICOM browser.

I think the above could cause confusion.

We could use another word, but I would avoid "instance", since that would mislead users to think that it is raw DICOM value. What columns names are displayed in software that you have access to?

Avoiding instances is fine with me. "Count" or "#" could be a neutral name.

jcfr · 2019-04-15T17:41:21Z

What about adding an small icon on the right side of the "Description" in the column header. Mouse over the icon and it displays how the text was generated.

cpinter · 2019-04-15T17:53:12Z

How about this:
I change the ColumnDisplayProperties table defaults so that

Number of images will be '#'
Description will be 'Series description' and 'Study description' for the Series and Studies tables, respectively
Keep schema version the same, because the data tables do not change, so no update is necessary

cpinter · 2019-04-15T17:58:38Z

Thinking a bit more, I think '#' won't be good after all. We use that symbol for objects' number identifier. For example we have 'Series #' in the same table and also 'Echo #'.

What about 'Count' in the column header and 'DisplayedCount' in the schema. Note that a version bump will be needed after all.

…n DICOM browser - The displayed fields are in the same tables as the raw DICOM tags, with additional fields: - Timestamp fields for insertion and displayed field generation - Patients: displayed patient name (human readable), number of studies - Studies: number of series - Series: generic "size" column, and number of images and frames - A new ColumnDisplayProperties table is added that contains the display properties for the patient, study, series tables: - Displayed column name - Visibility - Weight: determines order, smaller values for columns towards the left ("heaviest sinks down") - Format: format strings for dates and names for example (TBD) ----------------- Original commits: ENH: Add option to confirm Remove action ENH: Add autoSelectSeries and selectionMode properties to DICOM table manager - autoSelectSeries property controls whether or not series are automatically selected when selection changes in the studies table - selectionMode can be single or extended selection. If autoSelectSeries property is on and single selection is active, then the first series is selected from the list ENH: Emit schemaUpdated when all steps are done; Reduce updates - schemaUpdated signal is now emitted as before: once all the schema update steps are finished - Column swaps now do not trigger geometry update on each swap in applyColumnProperties, which can be dozens of times - Make ctkDICOMTableView::tableView callable from python ENH: Add progress dialog for display fields update - Display fields update has now a progress dialog, implemented similarly to schema update and import - Coding style fixes ENH: New fields in DICOM database, display fields update speedup, schema update option - Add new size and number of frames fields - Considerable speedup of updateDisplayedFields by wrapping the apply step (update queries) in a transaction - Add property in DICOM browser for schema update option, which determines whether to always update schema, never do it, or ask user. Default is always update - Fix typos and style ENH: Add patient and study numbers to DICOM tables ENH: Allow setting column display properties Column display properties of the DICOM database can now be set externally. When it happens, then - Update ColumnDisplayProperties table in database - Trigger applyColumnProperties to update table view (header name, visibility, and order for columns) Patient sex is now a visible column in the patient table by default ENH: Add support for DICOM table column weights The column with the lower weight is towards the left. Defaults are set, which show the same order as before, except for two changes - Human-readable patient name is on the left in the patients table and the raw patient name is not visible any more - Date added column is the rightmost in all tables ENH: Generate human-readable patient name ENH: Add calculation of number of images in series STYLE: Document displayed field generator classes ENH: Apply column display properties in DICOM table view - DICOM table view applies column display properties from database - Clean up style in ctkDICOMTableView ENH: Column properties initialization - Fill ColumnDisplayProperties table with the defaults - Weight and Format fields are not yet utilized! - Add functions to get column display properties - Rearrange functions in ctkDICOMDatabase so that Private functions are together - Further cleaning up style ENH: Set displayed fields updated timestamps - Type of DisplayedFieldsUpdatedTimestamp field changed to DATETIME for easier comparison when doing SELECT - Set the value of the field when applying the displayed fields - Fix many of the indentation problems (there are 3 different styles in this one class alone) ENH: Add DICOM displayed fields in the original database tables - Instead of separate tables, the displayed fields are now in the same tables as the raw DICOM tags, with additional timestamp fields for insertion and displayed field generation - A new ColumnDisplayProperties table is added that contains the display properties for the patient, study, series tables: - Displayed column name - Visibility - Weight: determines order, smaller values for columns towards the left ("heaviest sinks down") - Format: format strings for dates and names for example (TBD) ENH: DICOM browser shows display tables ENH: Pass cached tags by reference to DICOM displayed field roles ENH: Use display tables to allow showing derived and custom columns in DICOM browser !WIP! Original commits: COMP: Fixed merge issues in display table merge, builds fine Fixed bug when split DICOM data was inserted one after the other in Display* tables Deletion from database works for display tables too; Some bugfixes Inserting one patient/study/series has the expected result in the Display* tables Fixed function signatures for getting display fields Changed way of getting the display field maps Generate and use internal patient UID for the display tables WIP Add UIDs in the display tables ctkDICOMDatabase::getCachedTags changed to return empty string if the cached field is empty or the field is not in the instance Fixed rules (still WIP) Added merge helper functions Added initial implemntation for default displayed field generator rule Empty field names are passed to the mergeDisplayFieldsForInstance function Added empty names maps; Implemented getDisplayFieldsForInstance for the RT series description rule Changed DisplayPatients table schema: renamed MRN to PatientID; Added role headers in the CMakeLists file Completed rule interface Fixed new files query for updateDisplayedFields; Added applyDisplayFieldsChanges method to insert or update display fields after generation is done Added skeleton of ctkDICOMDisplayedFieldGenerator and a few example rules Added skeleton for ctkDICOMDatabase::updateDisplayedFields Input data assembled and passed to the displayed field generator (not tested) Update display fields method body implemented Added display tables to DICOM database schema; Merged from lassoan/276-dicom-database-display-tables

cpinter · 2019-04-15T18:25:50Z

I pushed the changes that prefix Description with Study/Series and rename 'Number of images' to 'Count'.

If this is fine for everyone, I'd appreciate if this could be merged soon. Thanks a lot!

jcfr · 2019-04-15T18:52:38Z

If this is fine for everyone, I'd appreciate if this could be merged soon. Thanks a lot!

Works for me.

I suggest we integrate at 4.30pm EST today.

fedorov · 2019-04-15T19:32:23Z

No concerns, thanks!

cpinter · 2019-04-15T20:57:15Z

Excellent, thanks! I'm doing a test build with Slicer then will update it to contain the CTK changes along with the new application setting for the DICOM database.

Please let me know if there are any issues with this one, or ideas for later.

fedorov · 2019-04-15T21:22:14Z

Please let me know if there are any issues with this one, or ideas for later.

Once you have examples / design patterns how DICOM plugins should initialize the new modality-specific column items, would be great if you could update this issue with the pointers!

- DICOM browser is now customizable and shows more informative fields. More information at commontk/CTK#858 - Add application setting for DICOM database update option. By default the user is asked whether they want to update or create new git-svn-id: http://svn.slicer.org/Slicer4/trunk@28142 3bd1e089-480b-0410-8dfb-8563597acbee

cpinter · 2019-04-15T22:07:31Z

The CTK hash has been updated (and the new app setting added) in Slicer/Slicer@75fceb2

I'll add information about how to create new plugins and what they can do. Jc suggested this page, and I think it's a good place for this: https://www.slicer.org/wiki/Documentation/Nightly/Modules/DICOM#Information_for_Developers

cpinter · 2019-04-16T16:05:09Z

FYI I updated the wiki page mentioned above.

jcfr · 2019-04-16T16:59:43Z

Thanks Csaba. If you would like to more easily reference classes in wiki text, you could use the doxygen template. See https://www.slicer.org/wiki/Documentation/Nightly/WikiCheatSheet#Doxygen

Examples are available here: https://www.slicer.org/wiki/Template:Documentation/Nightly/doxygen-class-url

- DICOM browser is now customizable and shows more informative fields. More information at commontk/CTK#858 - Add application setting for DICOM database update option. By default the user is asked whether they want to update or create new git-svn-id: http://svn.slicer.org/Slicer4/trunk@28142 3bd1e089-480b-0410-8dfb-8563597acbee

jcfr reviewed Apr 9, 2019

View reviewed changes

cpinter force-pushed the dicom-database-display-tables-4 branch from e3e5bea to 479a6da Compare April 11, 2019 16:47

cpinter force-pushed the dicom-database-display-tables-4 branch from 479a6da to 86b7e9d Compare April 11, 2019 18:01

cpinter force-pushed the dicom-database-display-tables-4 branch from 86b7e9d to 9c2af28 Compare April 15, 2019 18:24

jcfr merged commit 83cbf7e into commontk:master Apr 15, 2019

jcfr changed the title ~~ENH: Use display tables to allow showing derived and custom columns i…~~ ENH: Use display tables to allow showing derived and custom columns in DICOM browser Dec 14, 2022

jcfr mentioned this pull request Dec 14, 2022

Move PatientAge to study level #95

Closed

ENH: Use display tables to allow showing derived and custom columns in DICOM browser #858

ENH: Use display tables to allow showing derived and custom columns in DICOM browser #858

Conversation

cpinter commented Apr 9, 2019 • edited by jcfr Loading

cpinter commented Apr 9, 2019 • edited Loading

cpinter commented Apr 9, 2019

pieper commented Apr 9, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cpinter commented Apr 9, 2019

fedorov commented Apr 11, 2019

cpinter commented Apr 11, 2019

lassoan commented Apr 11, 2019

cpinter commented Apr 11, 2019

cpinter commented Apr 15, 2019

fedorov commented Apr 15, 2019 • edited Loading

fedorov commented Apr 15, 2019

cpinter commented Apr 15, 2019

fedorov commented Apr 15, 2019

lassoan commented Apr 15, 2019 • edited Loading

fedorov commented Apr 15, 2019

jcfr commented Apr 15, 2019

cpinter commented Apr 15, 2019

cpinter commented Apr 15, 2019 • edited Loading

cpinter commented Apr 15, 2019

jcfr commented Apr 15, 2019

fedorov commented Apr 15, 2019

cpinter commented Apr 15, 2019

fedorov commented Apr 15, 2019

cpinter commented Apr 15, 2019

cpinter commented Apr 16, 2019 • edited Loading

jcfr commented Apr 16, 2019

cpinter commented Apr 9, 2019 •

edited by jcfr

Loading

cpinter commented Apr 9, 2019 •

edited

Loading

fedorov commented Apr 15, 2019 •

edited

Loading

lassoan commented Apr 15, 2019 •

edited

Loading

cpinter commented Apr 15, 2019 •

edited

Loading

cpinter commented Apr 16, 2019 •

edited

Loading