Purpose

This module implements multiple and configurable prefilter steps, for example on files imported with DirectDicomImport. One or more FileListFilterPlugin modules can be connected to DirectDicomImport to influence the import process and to determine which files are used and which not.

Each file can be labelled or a so-called Pass-flags can be set or cleared to determine whether the file is fed into the import process or not. The label can be used to define file groups which are imported in their own import steps. The DPL configuration defined in a tab can be assigned to a set of files in a similar way to control the volume partitioning during import.

There are three filters which can be applied to each file:

-The File Path Filter is a regular expression on the absolute path with file name of the file.

-The Tag String Filter is a regular expression on the string representation of a DICOM tag value.

-The Tag Value Filter is a function expression on the numeric representation of up to four DICOM tag values.

The filters are applied in this order and can explicitly be activated or deactivated.

Finally the Pass flag which results from those filters determines whether each file is imported or not.

Multiple FileListFilterPlugin can be cascaded such that their pass flags result to a combination of AND and OR operations. By using flags such as Clear Pass Flag Before Filtering and other clear/set-Pass flags operations this can explicitly be controlled by the user.

Usage

-Select which of the File Path Filter, the Tag String Filter or the Tag Value Filter shall be applied to the files or to their DICOM tags which are found for importing. Enable the flags Apply File Path Filter, Apply tag string value filter, and/or Apply tag numeric value filter for that purpose.

-Determine whether or under which circumstances files shall get a label to make same-labelled files be imported in their own import step.

-Connect the filter plugin to the DirectDicomImport modules which shall make use of the filtering and labelling.

-Consider whether other filter plugins connected to the input shall apply further filter and labelling steps.

Windows

Default Panel

../../../Projects/DICOM/MLFileListTools/Modules/mhelp/Images/Screenshots/FileListFilterPlugin._default.png

Input Fields

inputFilterPlugin

name: inputFilterPlugin, type: MLBase

Modules derived from the base class FileListFilterPluginBase can be cascaded. This makes it possible to apply multiple filter steps where each filter can provide different properties. The number of connected filter plugins is not limited. The output of a FileListFilterPlugin therefore can be connected either directly to the input of a DirectDicomImport or alternatively to the input of another FileListFilterPlugin. The plugin directly connected to the DirectDicomImport module is called first, all other filter plugins are called according to their order in the connection pipeline.

Output Fields

outputFilterPlugin

name: outputFilterPlugin, type: MLBase

See inputFilterPlugin for details.

Parameter Fields

Visible Fields

Volume Label

name: volumeLabel, type: String

This label can be assigned to files while filtering takes place. Whether it is assigned or not depends on the Label Assign Mode.

Volume Config

name: volumeConfig, type: String, default: (,   {Element = (0008,0060); Name = Modality;  Sort = 1; Part = 1; },,   {Element = (0008,0020); Name = StudyDate; Sort = 1; Part = 1; },,   {Element = (0008,0008); Name = ImageType; Sort = 1; Part = 1; },,   {Element = (0018,1030); Name = ProtocolName; Sort = 1; Part = 1; },,   {Element = (0018,0050); Name = SliceThickness; Sort = 1; Part = 1; Tolerance = 0.000005; },,   {Element = (0018,0080); Name = RepetitionTime; Sort = 1; Part = 1; },,   {Element = (0018,0082); Name = InversionTime; Sort = 1; Part = 1; },,   {Element = (0018,0091); Name = EchoTrainLength; Sort = 1; Part = 1; },,   {Element = (0018,1210); Name = ConvolutionKernel; Sort = 1; Part = 1; },,   {Element = (0018,1314); Name = FlipAngle; Sort = 1; Part = 1; },,   {Element = (0018,0015); Name = BodyPartExamined; Sort = 1; Part = 1; },,   {Element = (0028,0008); Name = NumberOfFrames; Sort = 1; Part = 1; },,   {Element = (0028,0010); Name = Rows; Sort = 1; Part = 1; },,   {Element = (0028,0011); Name = Columns; Sort = 1; Part = 1; },,   {Element = (0020,0037); Name = ImageOrientationPatient; Sort = 1; Part = 1; Tolerance = 0.000005; },,   {Element = (0018,1004); Name = PlateID; Sort = 1; Part = 1; },,   {Element = (0018,1000); Name = DeviceSerialNumber; Sort = 1; Part = 1; },,   {Element = (0028,0004); Name = PhotometricInterpretation; Sort = 1; Part = 1; },,   {Element = (0028,0100); Name = BitsAllocated; Sort = 1; Part = 1; },,   {Element = (0028,0102); Name = HighBit; Sort = 1; Part = 1; },,   {Element = (0028,0103); Name = PixelRepresentation; Sort = 1; Part = 1; },,   {Element = (0018,0020); Name = ScanningSequence; Sort = 1; Part = 1; },,   {Element = (0018,0023); Name = MRAcquisitionType; Sort = 1; Part = 1; },,   {Element = (0028,0030); Name = PixelSpacing; Sort = 1; Part = 1; Tolerance = 0.00001; },,   {Element = (0054,0010); Name = EnergyWindowVector; Sort = 1; Part = 1; },,   {Element = (0054,0030); Name = PhaseVector; Sort = 1; Part = 1; },,   {Element = (0054,0060); Name = RRIntervalVector; Sort = 1; Part = 1; },,   {Element = (0054,0050); Name = RotationVector; Sort = 1; Part = 1; },,   {Element = (0020,000e); Name = SeriesInstanceUID; Sort = 1; SortCondition = "Modality = NM & !(FrameIncrementPointer = '(0054,0010)')" Part = 1; PartCondition = "Modality = NM & !(FrameIncrementPointer = '(0054,0010)')";       },,   {Element = (0008,0018); Name = SOPInstanceUID; Sort = 1; SortCondition = "Modality = NM & NumberOfFrames > 1";  Part = 1; PartCondition = "Modality = NM & NumberOfFrames > 1";  },,   {Element = (0008,0018); Name = SOPInstanceUID; Sort = 1; SortCondition = "Modality = CR | Modality = DR | Modality = MG | Modality = MX" Part = 1; PartCondition = "Modality = CR | Modality = DR | Modality = MG | Modality = MX";  },,   {Element = (0008,1090); Name = ManufacturerModelName; Sort = 1; Part = 1; },,   {Element = (0008,1010); Name = StationName; Sort = 1; Part = 1; },,   {Element = (0008,0070); Name = Manufacturer; Sort = 1; Part = 1; },,   {Element = (0018,0020); Name = ScanningSequence; Sort = 1; Part = 1; },,   {Element = (0018,0085); Name = ImagedNucleus; Sort = 1; Part = 1; },,   {Element = (0018,0087); Name = MagneticFieldStrength; Sort = 1; Part = 1; },,   {Element = (0018,1020); Name = SoftwareVersion; Sort = 1; Part = 1; },,   {Element = (0018,5100); Name = PatientPosition; Sort = 1; Part = 1; },,   {Element = (0062,000b); Name = ReferencedSegmentNumber; Sort = 1; Part = 1;  PartCondition = "SOPClassUID = 1.2.840.10008.5.1.4.1.1.66.4"; },,   {Element = (0020,000e); Name = SeriesInstanceUID; Sort = 1; Part = 1; PartCondition = "SOPClassUID = 1.2.840.10008.5.1.4.1.1.66.4"; },,   {Element = (0020,0013); Name = InstanceNumber; Sort = 1; Part = 0; },,   {Element = (0008,0030); Name = StudyTime; Sort = 1; Part = 0; },,   {Element = (0020,0011); Name = SeriesNumber; Sort = 1; Part = 0; },,   {Element = (0008,0021); Name = SeriesDate; Sort = 1; Part = 0; },,   {Element = (0008,0031); Name = SeriesTime; Sort = 1; Part = 0; },,   {Element = (0018,0081); Name = EchoTime; Sort = 1; Part = 0; },,   {Element = (0018,0024); Name = SequenceName; Sort = 1; Part = 0; },,   {Element = (0020,0012); Name = AcquisitionNumber; Sort = 1; Part = 0; },,   {Element = (0018,0022); Name = ScanOptions; Sort = 1; Part = 0; },,   {Element = (0008,0022); Name = AcquisitionDate; Sort = 1; Part = 0; },,   {Element = (0008,0032); Name = AcquisitionTime; Sort = 1; Part = 0; },,   {Element = (0008,0023); Name = ContentDate; Sort = 1; Part = 0; },,   {Element = (0008,0033); Name = ContentTime; Sort = 1; Part = 0; },,   {Element = (0020,0032); Name = ImagePositionPatient; Sort = 1; Part = 0; },,   {Element = (0054,0020); Name = DetectorVector; Sort = 1; Part = 0; },,   {Element = (0054,0100); Name = TimeSliceVector; Sort = 1; Part = 0; },,   {Element = (0054,0070); Name = TimeSlotVector; Sort = 1; Part = 0; },,   {Element = (0054,0080); Name = SliceVector; Sort = 1; Part = 0; },,   {Element = (0054,0090); Name = AngularViewVector; Sort = 1; Part = 0; },, ),, deprecated name: importConfig

This is a DPL configuration which can be assigned to files dependent on the Config Assign Mode. This DPL configuration will be used for all files which have the same label and the same configuration when they are imported by the DirectDicomImport. Any DPL configurations which might be selected by the user or by default in the DirectDicomImport will be overridden. In this way a filter can determine very specific DPL configuration for a set of files.

Processing Settings

name: processingSettings, type: String

In this field a number of line-wise defined settings can be assigned to files according to the Processing Settings Assign Mode. If it is assigned then it may be interpreted by file importers in an importer-specific way. Note that these settings typically are case sensitive and no spaces are allowed between tag, ‘=’, and the tag value, unless explicitly described as <Space>. If spaces are needed (for example in tag values) then they must be escaped with <sp>. If a tag appears multiply then normally the last one used, and tags which cannot be identified or with wrong values are silently ignored. Check log files of importers whether values are actually used. Currently the following tags are known to be supported by the DPL importer of DirectDicomImport, see similar named fields in the importer for documentation:

  • DPL_absoluteDistanceTolerance=<DoubleValue greater than 0>
  • DPL_allowMixedPixelTypes=0 or 1
  • DPL_allowSortingAccordingToDimensionIndexValues=<Auto|Off>
  • DPL_anon=0 or 1
  • DPL_applySetNGoSeriesPostProcessor=0 or 1
  • DPL_applySetNGoSeriesOnlyPostProcessor=0 or 1
  • DPL_calcMinMax=Automatic|ScanImageData|OnlyFromDicomTags
  • DPL_copyPrivateTopLevelSourceTags=0 or 1
  • DPL_force2DPlusTCondition=<ConditionString>
  • DPL_forceOrthogonalWorldMatrix=0 or 1
  • DPL_logPartingAndSortingInformation=0 or 1
  • DPL_minimumNumFramesInVolume=<UnsignedIntValue greater than 0>
  • DPL_positionToleranceMM=<DoubleValue>
  • DPL_relativeDistanceTolerance=<DoubleValue greater than 0>
  • DPL_removePrivateMFSQTag=0 or 1
  • DPL_seriesBasedPreprocessingCondition=0 or 1
  • DPL_splitTimePointsTo3DVolumes=0 or 1
  • DPL_verbose=0 or 1
  • DPL_userTagReplacement0=<TagId><Space><TagValueWithoutWhiteSpaces>
  • DPL_userTagReplacement1=<TagId><Space><TagValueWithoutWhiteSpaces>
  • DPL_userTagReplacement2=<TagId><Space><TagValueWithoutWhiteSpaces>
  • DPL_userTagReplacement3=<TagId><Space><TagValueWithoutWhiteSpaces>
  • DPL_workaroundValueForImageOrientationPatientTag=<ImageOrientationPatientVal>

with

  • 0 or 1: Any of the values 0 or 1
  • <DoubleValue…>: a normal double precision floating point value
  • <Unsigned32BitIntValue…>: a 32 bit decimal value without sign
  • <TagId>: is something like (ABCD,EFGH) where ABCD and EFGH are 4-digit hexadecimal numbers such as (0008,0060) or the corresponding tag name such as Modality
  • <Space>: is a single space character
  • <TagValueWithoutWhiteSpaces>: is a numerical or text tag value without (white) spaces (spaces can be inserted with <sp>)
  • <ConditionString>: An expression for example such as Modality == XA | Modality == US in which spaces are escaped: Modality<sp>==<sp>XA<sp>|<sp>Modality<sp>==<sp>US
  • <ImageOrientationPatientVal> a value such as 1\0\0\0\1\0 which complies as ImageOrientationPatient DICOM tags value

Clear Pass Flag Before Filtering

name: clearPassFlagBeforeFiltering, type: Bool, default: FALSE

If enabled (default is off) then the pass flag will be cleared before any filtering is applied. This especially can be useful if multiple filter plugins are cascaded. Activating this flag usually makes sense only in the first FileListFilterPlugin of a cascaded list, because it clears all pass flags possibly be set in previously evaluated instances.

Label Assign Mode

name: labelAssignMode, type: Enum, default: DoNotChangeLabel

Describes under which condition the value of Volume Label is assigned to the attributes of a file.

Values:

Title Name Description
Set Label If Expression Matches SetLabelIfExpressionMatches The label is assigned if any expression matches.
Set Label If Expression Does Not Match SetLabelIfExpressionDoesNotMatch The label is assigned if any activated filter expression does not match.
Set Label If Pass Flag Is True SetLabelIfPassFlagIsTrue The label is assigned if after filtering the pass flag is true or if it was already true before.
Set Label If Pass Flag Is False SetLabelIfPassFlagIsFalse The label is assigned if after filtering the pass flag is false or if it was false before.
Set Label If Pass Flag Is Set SetLabelIfPassFlagIsSet The label is assigned if the pass flag is set to true (independent of its previous state).
Set Label If Pass Flag Is Cleared SetLabelIfPassFlagIsCleared The label is assigned if the pass flag is set to false (independent of its previous state).
Set Label If Pass Flag Is Unchanged SetLabelIfPassFlagIsUnchanged The label is assigned if the pass flag is neither set nor cleared by the filter.
Do Not Change Label DoNotChangeLabel The label in the file attributes is not changed at all.

Config Assign Mode

name: configAssignMode, type: Enum, default: DoNotChangeConfig

Describes under which condition the value of Volume Config is assigned to the attributes of a file.

Values:

Title Name Description
Do Not Change Config DoNotChangeConfig The DPL configuration in the file attributes is not changed at all.
Set Config If Expression Matches SetConfigIfExpressionMatches The DPL configuration is assigned if any expression matches.
Set Config If Expression Does Not Match SetConfigIfExpressionDoesNotMatch The DPL configuration is assigned if any activated filter expression does not match.
Set Config If Pass Flag Is True SetConfigIfPassFlagIsTrue The DPL configuration is assigned if after filtering the pass flag is true or if it was already true before.
Set Config If Pass Flag Is False SetConfigIfPassFlagIsFalse The DPL configuration is assigned if after filtering the pass flag is false or if it was false before.
Set Config If Pass Flag Is Set SetConfigIfPassFlagIsSet The DPL configuration is assigned if the pass flag is set to true (independent of its previous state).
Set Config If Pass Flag Is Cleared SetConfigIfPassFlagIsCleared The DPL configuration is assigned if the pass flag is set to false (independent of its previous state).
Set Config If Pass Flag Is Unchanged SetConfigIfPassFlagIsUnchanged The DPL configuration is assigned if the pass flag is neither set nor cleared by the filter.

Processing Settings Assign Mode

name: processingSettingsAssignMode, type: Enum, default: DoNotChangeProcSettings

Determines when the line-wise processing settings shall be assigned to a file.

Values:

Title Name
Do Not Change Proc Settings DoNotChangeProcSettings
Set Proc Settings If Expression Matches SetProcSettingsIfExpressionMatches
Set Proc Settings If Expression Does Not Match SetProcSettingsIfExpressionDoesNotMatch
Set Proc Settings If Pass Flag Is True SetProcSettingsIfPassFlagIsTrue
Set Proc Settings If Pass Flag Is False SetProcSettingsIfPassFlagIsFalse
Set Proc Settings If Pass Flag Is Set SetProcSettingsIfPassFlagIsSet
Set Proc Settings If Pass Flag Is Cleared SetProcSettingsIfPassFlagIsCleared
Set Proc Settings If Pass Flag Is Unchanged SetProcSettingsIfPassFlagIsUnchanged

Check Only First Recursive Tag String

name: checkOnlyFirstRecursiveTagString, type: Bool, default: TRUE

Only used if Allow Recursive Tag Search tag search is on: if Check Only First Recursive Tag String is off, then all tags in the tree are scanned for a matching expression (which may be significantly slower and memory intensive), otherwise only the first found one is evaluated.

Apply File Path Filter

name: applyFilePathFilter, type: Bool, default: TRUE

If enabled then filtering of path strings is applied, otherwise it is ignored without changing any flags or labels. If disabled then the expression is ignored and not evaluated.

Expression to match

name: pathFilterRegEx, type: String, default: .*

Regular expression for path filtering.

Invert (invertPathFilterRegEx)

name: invertPathFilterRegEx, type: Bool, default: FALSE

Inverts the matching result of the regular expression if checked.

Set pass flag if path matches expression

name: setPassFlagOnPathMatches, type: Bool, default: FALSE

If enabled and if Expression to match matches the path then the pass flag is set.

Clear pass flag if path mismatches expression

name: clearPassFlagOnPathMismatches, type: Bool, default: TRUE

If enabled and if Expression to match does not match the path then the pass flag is cleared.

Reg Ex Status

name: regExStatus, type: String

Shows error messages or status information for path filtering if needed.

Apply tag string value filter

name: applyTagStringFilter, type: Bool, default: FALSE

If enabled then filtering of tag values (converted to strings) is applied, otherwise it is ignored without changing any flag, label or configurations. Note that tag string filtering is not applied at all (even if enabled) if the file is not a DICOM file, thus no flags, labels, or configurations are cleared, set, or assigned.

Tag String Filter Tag Id

name: tagStringFilterTagId, type: String, default: (0000,0000)

Id of the tag whose string value shall be filtered with a regular expression. The format of the id must be like (GHIJ,KLMN), where the digits G, H, I, J, K, L, M, N represent hexadecimal values from [0,1,2,3,4,5,6,7,8,9,a,b,c,d,e,f,A,B,C,D,E,F].

Value Index

name: tagStringFilterTagValueIndex, type: Integer, default: -1, minimum: -1

If < 0 then multi-valued tag values are handled as a composed string where all values are separated with backslashes; otherwise the selected value at the given index is selected. If an index >= 0 outside the valid value range is specified then an empty value is used.

Private Creator

name: tagStringFilterPrivateCreator, type: String

According to the DICOM standard on an odd group id in Tag String Filter Tag Id the actual id can only be determined by finding the private element group id (bits 8-15) which is defined in the lower eight bit of the id of the private creator whose string name is defined here. This private element group id then replaces the value in bits 8-15 of the Tag String Filter Tag Id to determine the actual tag id. This field is used only if Tag String Filter Tag Id has an odd group id, otherwise it is ignored.

Expression To Match Tag Value

name: tagStringEvalRegEx, type: String, default: .*

Regular expression for filtering of tag values (converted to strings).

Invert (invertTagStringEvalRegEx)

name: invertTagStringEvalRegEx, type: Bool, default: FALSE

Inverts the matching result of the regular expression if checked.

Set pass flag if tag string matches expression

name: setTagStrEvalPassFlagOnPathMatches, type: Bool, default: FALSE

If enabled and if Expression To Match Tag Value matches the tag value (converted to string) then the pass flag is set.

Clear pass flag if tag string mismatches expression

name: clearTagStrEvalPassFlagOnPathMismatches, type: Bool, default: TRUE

If true (the default) then a non matching Expression To Match Tag Value on the tag value will clear the pass flag and the file will not be imported. This is useful if filter plugins are cascaded in ‘AND’ mode (the default)where any non matching filter plugin clears the pass flag. If enabled and if does not match the tag value (converted to string) then the pass flag is cleared.

Tag Filter Reg Ex Status

name: tagFilterRegExStatus, type: String

Shows regular expression status and error information if necessary.

Apply tag numeric value filter

name: applyTagValueFilter, type: Bool, default: FALSE

If enabled then the numeric expression is evaluated on numeric representations of DICOM tags of the file, and its result must be in [Range Min, Range Max] to make the expression match. If disabled then the expression is ignored and not evaluated. Note that no evaluations take place (even if enabled) if the file is not a DICOM file, thus no flags, labels, or configurations are cleared, set, or assigned.

Expression

name: treeFilterEx, type: String, default: 0

Expression evaluated for each valid DICOM tree. Constants 0, 1, 2, and 3 and values 0, 1, 2, and 3 read from tags as numeric values can be used. Result must be in Range Min and Range Max make the expression match.

0 (tagId0)

name: tagId0, type: String, default: (0000,0000)

Id of dicom tag whose value can be used as t0 in numeric expression.

Tag Id0Value Index

name: tagId0ValueIndex, type: Integer, default: -1, minimum: -1

Useful for multi-values tags: if this field is <= 0 then the first value of a tag value is used as expression value, otherwise the value at the given index is used. If the index is >= 0 but outside the valid value range then 0 is used instead.

0 (tagId0PrivateCreator)

name: tagId0PrivateCreator, type: String

Private creator string used if 0 has a private (odd) group id, see Private Creator for details.

1 (tagId1)

name: tagId1, type: String, default: (0000,0000)

Id of dicom tag whose value can be used as t1 in numeric expression.

Tag Id1Value Index

name: tagId1ValueIndex, type: Integer, default: -1, minimum: -1

Useful for multi-values tags: if this field is <= 0 then the first value of a tag value is used as expression value, otherwise the value at the given index is used. If the index is >= 0 but outside the valid value range then 0 is used instead.

1 (tagId1PrivateCreator)

name: tagId1PrivateCreator, type: String

Private creator string used if 1 has a private (odd) group id, see Private Creator for details.

2 (tagId2)

name: tagId2, type: String, default: (0000,0000)

Id of dicom tag whose value can be used as t2 in numeric expression.

Tag Id2Value Index

name: tagId2ValueIndex, type: Integer, default: -1, minimum: -1

Useful for multi-values tags: if this field is <= 0 then the first value of a tag value is used as expression value, otherwise the value at the given index is used. If the index is >= 0 but outside the valid value range then 0 is used instead.

2 (tagId2PrivateCreator)

name: tagId2PrivateCreator, type: String

Private creator string used if 2 has a private (odd) group id, see Private Creator for details.

3 (tagId3)

name: tagId3, type: String, default: (0000,0000)

Id of dicom tag whose value can be used as t3 in numeric expression.

Tag Id3Value Index

name: tagId3ValueIndex, type: Integer, default: -1, minimum: -1

Useful for multi-values tags: if this field is <= 0 then the first value of a tag value is used as expression value, otherwise the value at the given index is used. If the index is >= 0 but outside the valid value range then 0 is used instead.

3 (tagId3PrivateCreator)

name: tagId3PrivateCreator, type: String

Private creator string used if 3 has a private (odd) group id, see Private Creator for details.

0 (const0)

name: const0, type: Double, default: 0

Constant 0 which can be used as c0 in numeric expression.

1 (const1)

name: const1, type: Double, default: 0

Constant 1 which can be used as c1 in numeric expression.

2 (const2)

name: const2, type: Double, default: 0

Constant 2 which can be used as c2 in numeric expression.

3 (const3)

name: const3, type: Double, default: 0

Constant 3 which can be used as c3 in numeric expression.

Range Min

name: rangeMin, type: Double, default: -1

Minimum value of the interval in which the expression result must be to make the expression match.

Range Max

name: rangeMax, type: Double, default: 1

Maximum value of the interval in which the expression result must be to make the expression match.

Set pass flag if expression result is in range.

name: setPassFlagOnTagValueMatches, type: Bool, default: FALSE

If enabled and if Expression result matches [Range Min,:field:rangeMax] then the pass flag is set.

Clear pass flag if expression result is out of range.

name: clearPassFlagOnTagValueMismatches, type: Bool, default: TRUE

If enabled and if Expression result does not match [Range Min,:field:rangeMax] then the pass flag is cleared.

Numeric tag filter status

name: treeFilterStatus, type: String

Shows status of Expression numeric expression and error information if necessary.

Hidden Fields

instanceName

name: instanceName, type: String, default: FileListFilterPlugin