DICOM Attribute Filter

The Attribute filter defines which attributes of the DICOM header are written into the BLOB field of patient/study/series/instance level and are therefore accessible during C-FIND.

Update Strategy

The behavior how the extracted attributes in the BLOB fields are updated by received objects of the same entity (Patient/Study/Series/Instance) can be controlled by the value of the attribute update-strategy of the <patient>, <study>, <series>, <instance> element. Enumerated values are

Fuzzy Person Name Matching

Fuzzy (phonetic) person name matching is activated by default with soundex as phonetic algorithm.
To meet the phonetic requirements of your language areas diffrent phonetic algorithm implementations are provided.
The parameter "soundex class" configures the algorithn to be used. Only one "soundex class" can be active.

To deactivate the possibility to perform a fuzzy person name search the "soundex class" has to be removed from the attribute filter configuration (e.g. by commenting the line out).

If you performed an update from a version < 2.16.0 OR changed the "soundex class" you have to invoke each updateXXXXName method in the "Soundex MBean" once. This will fill/modify the columns in the database, which hold the phonetic represantations of first and given name of the according person name.

Available phonetic Algorithms

org.dcm4che2.soundex.Soundex

Classic SoundEx Algorithms with retaining the first letter of the word and using coding table:

for remaining letters. Vowels and 'Y', 'H' and 'W' and adjacent consonants with equal soundex code are ignored and the resulting code is truncated/padded by '0' to a code length of 4 (first letter + 3 digits).

org.dcm4che2.soundex.ESoundex

Extended Soundex which does not retain the first letter and without truncation/padding of the resulting code to a code length of 4.

org.dcm4che2.soundex.ESoundex2

Extended Soundex like ESoundex, but also using an extended coding table:

org.dcm4che2.soundex.Metaphone

Implementation of the Metaphone algorithm as described at Wikipedia .

class org.dcm4che2.soundex.KPhonetik

Implementation of the algorithm as described in H.J. Postel, Die Koelner Phonetik
Ein Verfahren zu Identifizierung von Personennamen auf der Grundlage der Gestaltanalyse. IBM-Nachrichten 19 (1969), 925-931

s.a. Wikipedia

org.dcm4che2.soundex.Phonem

Implementation of the PHONEM substitutions, as described in Georg Wilde and Carsten Meyer, Doppelgaenger gesucht - Ein Programm fuer kontextsensitive phonetische Textumwandlung
ct Magazin fuer Computer & Technik 25/1998

Martin Wilz: Aspekte der Kodierung phonetischer Ähnlichkeiten in deutschen Eigennamen

Configuration

Sample for soundex as active "soundex class":

    <soundex class="org.dcm4che2.soundex.Soundex" trailing-wildcard="false"/>
    <!--
    <soundex class="org.dcm4che2.soundex.ESoundex"/>
    <soundex class="org.dcm4che2.soundex.ESoundex2"/>
    <soundex class="org.dcm4che2.soundex.KPhonetik"/>
    <soundex class="org.dcm4che2.soundex.Metaphone"/>
    <soundex class="org.dcm4che2.soundex.Phonem"/>
    -->

Wildcard matching at the end of a person name component is deactivatable by additional attribute trailing-wildcard of XML element <soundex>:

<!ATTLIST soundex trailing-wildcard (true | false) "true">

e.g.:

<soundex class="org.dcm4che2.soundex.Soundex" trailing-wildcard="false"/>

Because Soundex only considers the initial character and following 3 consonants, and pads shorter codes by '0' to 4 character, support of trailing wildcard matchings does not make sense with this algorithm

Case-sensitivity of matching string attributes

Case-sensitivity of matching string attributes can be controlled by the value of the attribute case-sensitive="true"|"false" of element <tag>. Default: "true". Only effective, for string attributes, for which matching is supported. For supported matching string attributes in sequence items, the tag of the sequence attribute shall be specified by an additional seq attribute of <tag>.

Supported matching string attributes

<patient>
  <attr tag="00100010" case-sensitive="false"/> <!-- Patient's Name -->
  <attr tag="00100020"/> <!-- Patient ID -->
  <attr tag="00100021"/> <!-- Issuer of Patient ID -->
  <attr tag="00100040"/> <!-- Patient's Sex -->
<patient>
<study>
  <attr tag="00080050"/> <!-- Accession Number -->
  <attr tag="00080090" case-sensitive="false"/> <!-- Referring Physician Name -->
  <attr tag="00081030" case-sensitive="false"/> <!-- Study Description -->
  <attr tag="0020000D"/> <!-- Study Instance UID -->
  <attr tag="00200010"/> <!-- Study ID -->
  <attr tag="0032000A"/> <!-- Study Status ID -->
</study>
<series>
  <attr tag="00080060"/> <!-- Modality -->
  <attr tag="00080070"/> <!-- Manufacturer -->
  <attr tag="00080080" case-sensitive="false"/> <!-- Institution Name -->
  <attr tag="00081010" case-sensitive="false"/> <!-- Station Name -->
  <attr tag="0008103E" case-sensitive="false"/> <!-- Series Description -->
  <attr tag="00081040" case-sensitive="false"/> <!-- Institutional Department Name -->
  <attr tag="00081050" case-sensitive="false"/> <!-- Performing Physician Name -->
  <attr tag="00081090"/> <!-- Manufacturer Model Name -->
  <attr tag="00180015"/> <!-- Body Part Examined -->
  <attr tag="0020000E"/> <!-- Series Instance UID -->
  <attr tag="00200011"/> <!-- Series Number -->
  <attr seq="00400275" tag="00321032" case-sensitive="false"/> <!-- Requesting Physician -->
  <attr seq="00400275" tag="00321033"/> <!-- Requesting Service -->
  <attr seq="00400275" tag="00400009"/> <!-- Scheduled Procedure Step ID -->
  <attr seq="00400275" tag="00401001"/> <!-- Requested Procedure ID -->
</series>
<instance>
  <attr tag="00080016"/> <!-- SOP Class UID -->
  <attr tag="00080018"/> <!-- SOP Instance UID -->
  <attr tag="00200013"/> <!-- Instance Number -->
  <attr seq="0040A073" tag="0040A075" case-sensitive="false"/> <!-- Verifying Observer Name -->
  <attr tag="0040A491"/> <!-- Completion Flag -->
  <attr tag="0040A493"/> <!-- Verification Flag -->
</instance>

Configurable Attributes extracted from received HL7 ORM^O01, DICOM MPPS, GP-PPS, UPS

Patient attributes extracted from received HL7 ORM^O01, DICOM MPPS, GP-PPS, UPS are configurable by considering

<patient>
  <attr tag="00080005"/> <!-- Specific Character Set -->
  <attr tag="00100010" case-sensitive="false"/> <!-- Patient's Name -->
  <attr tag="00100020"/> <!-- Patient ID -->
  <attr tag="00100021"/> <!-- Issuer of Patient ID -->
  <attr tag="00100030"/> <!-- Patient's Birth Date -->
  <attr tag="00100040"/> <!-- Patient's Sex -->
  <attr tag="00101002"/> <!-- Other Patient IDs Sequence -->
  <attr tag="00104000"/> <!-- Patient Comments -->
</patient>

in DCM4CHEE_HOMS/server/default/conf/dcm4chee-attribute-filter.xml, instead of hard-coded lists of patient attribute tags in java sources as in versions < 2.16.0.
Patient attributes excluded from the attributes, stored in the BLOB field of the specific (MWL, MPPS, PPS, UPS) DICOM object can be configured by

<exclude-patient exclude="true" tsuid="1.2.840.10008.1.2.1.99">
  <attr tag="00081120"/> <!-- Referenced Patient Sequence -->
  <attr tag="00100010"/> <!-- Patient's Name -->
  <attr tag="00100020"/> <!-- Patient ID -->
  <attr tag="00100021"/> <!-- Issuer of Patient ID -->
  <attr tag="00100030"/> <!-- Patient's Birth Date -->
  <attr tag="00100040"/> <!-- Patient's Sex -->
  <attr tag="00101002"/> <!-- Other Patient IDs Sequence -->
  <attr tag="00104000"/> <!-- Patient Comments -->
</exclude-patient>

Typically this list will differ from previous one by not including attribute Specific Character Set (0008,0005) - because it's also necessary for decoding String values of non-patient attributes - but including Referenced Patient Sequence (0008,1120) - which must be included in MPPS, but typically without value, so it does not make sense to extract into the Patient record attribute BLOB field.

Custom matching Attributes

It supports the configuration of up to 3 additional matching key on PATIENT, STUDY, SERIES and INSTANCE Level, configurable in conf/dcm4chee-attribute-filter.xml by new XML attribute field of <attr> element, which defines which DB column shall be mapped to this attribute to support it as matching key in DICOM Queries. Possible values for attribute field depends on the entity level:| Level | field value1 | field value2 | field value3 |

Example:

<dcm4chee-attribute-filter>
 [..]
 <series>
  [..]
   <attr tag="00180010" field="seriesCustomAttribute1"/> <\!-\- Contrast/Bolus Agent \-->
  [..]
 </series>
 [..]
</dcm4chee-attribute-filter>

will configure support of (0018,0010) Contrast/Bolus Agentas matching key on SERIES level

It is also possible to add private Attributes to custom_fields on study/series/instance level by:

1. Using the absolute tag value and also adding an entry for the corresponding Private Creator ID in conf/dcm4chee-attribute-filter.xml. E.g.:

   <study>
   :
   <attr tag="00990010"/> <!-- Private Creator ID -->
   <attr tag="00991015" field="studyCustomAttribute1"/> <!-- Private Attribute -->
   :
   </study>
   

2. Objects must not be stored with Implicit VR Little Endian - except, if the private attribute is added by a configured C-STORE RQ coercion in conf/dcm4chee-ae/MOD_AET/cstorerq.xsl. E.g.:

   <xsl:template match="/dataset">
   <dataset>
   <xsl:variable name="bodypartexamined" select="normalize-space(attr[@tag='00180015'])"/>
   <xsl:if test="$bodypartexamined">
   <attr tag="00990010" vr="LO">DCM4CHEE</attr>
   <attr tag="00991015" vr="CS">
   <xsl:value-of select="$bodypartexamined"/>
   </attr>
   </xsl:if>
   </dataset>
   </xsl:template>
   

3. Also Queries must be encoded with Explicit VR. E.g.:

   (0008,0020) DA #0 \[\] Study Date
   (0008,0030) TM #0 \[\] Study Time
   (0008,0050) SH #0 \[\] Accession Number
   (0008,0052) CS #6 [STUDY] Query/Retrieve Level
   (0020,000D) UI #0 \[\] Study Instance UID
   (0020,0010) SH #0 \[\] Study ID
   (0020,1206) IS #0 \[\] Number of Study Related Series
   (0020,1208) IS #0 \[\] Number of Study Related Instances
   (0099,0010) LO #8 [DCM4CHEE] Private Creator Data Element
   (0099,1015) CS #8 [ABDOMEN] Private Attribute
   

   Attention: At default configuration, only Transfer Syntax: Implicit VR Little Endian is accepted by the Query Retrieve Service of dcm4chee-archive for Standard Query Retrieve Services (QueryRetrieveSCP.AcceptedTransferSyntaxForStandardSOPClasses=ImplicitVRLittleEndian)!

Maximum length of Text value from content item sequence stored for DB queries

Text Values stored to DB field content_item.text_value are truncated to 250 characters by default configuration.

If it is desired to have more than the first 250 Bytes of a text value searchable the size of the DB field has to be increased and the maximum value length has to be added to the attribute filter:

<instance content-item-text-value-max-length='...'>