Parser for the Siemens private DICOM tag (0x0029, 0x1020) to extract CEST sequence parameters. More...

#include <mitkCustomTagParser.h>

Collaboration diagram for mitk::CustomTagParser:

Public Member Functions
	CustomTagParser (std::string relevantFile)
	Construct a CustomTagParser for DICOM files at the given path. More...

mitk::PropertyList::Pointer	ParseDicomProperty (mitk::TemporoSpatialStringProperty *dicomProperty)
	Parse a DICOM TemporoSpatialStringProperty and return extracted CEST parameters. More...

mitk::PropertyList::Pointer	ParseDicomPropertyString (std::string dicomPropertyString)
	Parse a hex-encoded DICOM tag string and return extracted CEST parameters. More...

void	SetParseStrategy (std::string parseStrategy)
	Set the strategy used to determine the type of CEST data. More...

void	SetRevisionMappingStrategy (std::string revisionMappingStrategy)
	Set the strategy for matching revision numbers to JSON parameter mappings. More...

Static Public Member Functions
static std::string	ReadListFromFile (const std::string &filePath)
	Read a space-separated list of values from a text file. More...

static std::string	ExtractRevision (std::string sequenceFileName)
	Extract the revision number from a CEST sequence file name. More...

Static Public Attributes
static const std::string	m_RevisionPropertyName
	Name of the property for the data acquisition revision ("CEST.Revision"). More...

static const std::string	m_JSONRevisionPropertyName
	Name of the property for the JSON parameter mapping revision ("CEST.revision_json"). More...

static const std::string	m_CESTPropertyPrefix
	Prefix for all CEST-related property names ("CEST."). More...

Protected Member Functions
std::string	GetRevisionAppropriateJSONString (std::string revisionString)

void	GetClosestLowerRevision (std::string revisionString)

std::string	GetClosestLowerRevision (std::string revisionString, std::vector< int > availableRevisionsVector)

bool	IsT1Sequence (std::string preparationType, std::string recoveryMode, std::string spoilingType, std::string revisionString)
	Decides whether or not the image is likely to be a T1Map, if not it is assumed to be a CEST sequence. More...

std::string	GetOffsetString (std::string samplingType, std::string offset, std::string measurements)
	Get a string filled with the properly formatted offsets based on the sampling type and offset. More...

std::vector< int >	GetExternalRevisions ()
	returns a vector revision numbers of all REVISIONNUMBER.json found beside the MitkCEST library More...

std::vector< int >	GetInternalRevisions ()
	returns a vector revision numbers of all REVISIONNUMBER.json provided as resources during the compile More...

std::string	GetExternalJSONDirectory ()
	returns the path where external jsons are expected to be located More...

Protected Attributes
std::string	m_ClosestInternalRevision
	the closest lower revision provided as resource, empty if none found More...

std::string	m_ClosestExternalRevision
	the closest lower revision provided as a json beside the library, empty if none found More...

std::string	m_DicomDataPath
	path to the dicom data More...

std::string	m_ParseStrategy
	Should the kind of data be automatically determined or should it be parsed as a specific one. More...

std::string	m_RevisionMappingStrategy
	How to handle parameter mapping based on absent revision jsons. More...

Static Protected Attributes
static const std::string	m_RevisionIndependentMapping
	revision independent mapping to inject into the revision dependent json string More...

static const std::string	m_DefaultJsonString
	default revision dependent json string if none is found More...

Detailed Description

Parser for the Siemens private DICOM tag (0x0029, 0x1020) to extract CEST sequence parameters.

The CustomTagParser can be used to parse the custom DICOM tag of the Siemens private tag (0x0029, 0x1020) to extract relevant CEST data and store it as an mitk::PropertyList.

An initial parsing determines whether the provided string belongs to CEST data at all. To make the check and extract the revision number the following rules are applied:

Sequence name (tSequenceFileName) must either
1. start with the substring "CEST" (case insensitive), or
2. contain the substring "_CEST" (case insensitive).
Sequence name (tSequenceFileName) must contain the substring "_Rev" (case insensitive).
All numbers after "_Rev" represent the revision number; until either
1. the next _, or
2. end of sequence name.

Which custom parameters to save and to which property name can be controlled by a JSON file. This file can be either provided as a resource for the MitkCEST module during compilation or placed next to the MitkCEST library in your binary folder.

The expected format for the file "REVISIONNUMBER.json":
{
"REVISIONNUMBER" : "revision_json",
"sWiPMemBlock.alFree[1]" : "AdvancedMode",
"sWiPMemBlock.alFree[2]" : "RetreatMode"
}

where :

REVISIONNUMBER is the revision number of this JSON parameter mapping (files with non-digit characters in their name will be ignored)
sWiPMemBlock.alFree[1] is the name of one parameter in the private DICOM tag
AdvancedMode is the name of the property the content of sWiPMemBlock.alFree[1] should be saved to

Note: It is assumed that the entire content of tag (0x0029, 0x1020) is provided and that it is hex encoded (12\23\04...).

If the sampling type is list, the parser will try to access LIST.txt at the location provided in the constructor to read the offsets. For T1 sequences, TREC.txt will be read from the same location.

See also: CESTImageNormalizationFilter, CESTPropertyHelper, ExtractCESTOffset

Definition at line 74 of file mitkCustomTagParser.h.

Constructor & Destructor Documentation

◆ CustomTagParser()

mitk::CustomTagParser::CustomTagParser ( std::string relevantFile )

Construct a CustomTagParser for DICOM files at the given path.

Parameters

[in] relevantFile Path to one of the DICOM files to be loaded, or the directory containing the DICOM files. The directory is used to locate LIST.txt or TREC.txt files for offset/T1 recovery time data.

Member Function Documentation

◆ ExtractRevision()

static std::string mitk::CustomTagParser::ExtractRevision ( std::string sequenceFileName )

static

Extract the revision number from a CEST sequence file name.

Applies the naming rules described in the class documentation to identify and extract the numeric revision substring from the sequence file name.

Parameters

[in] sequenceFileName The CEST sequence file name (e.g., "CEST_Rev1416_someSequence").

Returns: The revision number as a string, or an empty string if the file name is valid but contains no revision number after "_Rev".

Exceptions

mitk::Exception	if the file name does not contain a valid CEST prefix ("CEST" or "_CEST").
mitk::Exception	if the file name contains a CEST prefix but no "_Rev" substring.

◆ GetClosestLowerRevision() [1/2]

void mitk::CustomTagParser::GetClosestLowerRevision ( std::string revisionString )

protected

◆ GetClosestLowerRevision() [2/2]

std::string mitk::CustomTagParser::GetClosestLowerRevision	(	std::string	revisionString,
		std::vector< int >	availableRevisionsVector
	)

protected

◆ GetExternalJSONDirectory()

std::string mitk::CustomTagParser::GetExternalJSONDirectory ( )

protected

returns the path where external jsons are expected to be located

◆ GetExternalRevisions()

std::vector<int> mitk::CustomTagParser::GetExternalRevisions ( )

protected

returns a vector revision numbers of all REVISIONNUMBER.json found beside the MitkCEST library

◆ GetInternalRevisions()

std::vector<int> mitk::CustomTagParser::GetInternalRevisions ( )

protected

returns a vector revision numbers of all REVISIONNUMBER.json provided as resources during the compile

◆ GetOffsetString()

std::string mitk::CustomTagParser::GetOffsetString	(	std::string	samplingType,
		std::string	offset,
		std::string	measurements
	)

protected

Get a string filled with the properly formatted offsets based on the sampling type and offset.

◆ GetRevisionAppropriateJSONString()

std::string mitk::CustomTagParser::GetRevisionAppropriateJSONString ( std::string revisionString )

protected

◆ IsT1Sequence()

bool mitk::CustomTagParser::IsT1Sequence	(	std::string	preparationType,
		std::string	recoveryMode,
		std::string	spoilingType,
		std::string	revisionString
	)

protected

Decides whether or not the image is likely to be a T1Map, if not it is assumed to be a CEST sequence.

◆ ParseDicomProperty()

mitk::PropertyList::Pointer mitk::CustomTagParser::ParseDicomProperty ( mitk::TemporoSpatialStringProperty * dicomProperty )

Parse a DICOM TemporoSpatialStringProperty and return extracted CEST parameters.

Extracts the string value from the provided property and delegates to ParseDicomPropertyString().

Parameters

[in] dicomProperty Pointer to the TemporoSpatialStringProperty containing the hex-encoded Siemens private tag content. If nullptr, an error is logged and an empty PropertyList is returned.

Returns: A PropertyList containing the extracted CEST parameters with the "CEST." prefix.

See also: ParseDicomPropertyString

◆ ParseDicomPropertyString()

mitk::PropertyList::Pointer mitk::CustomTagParser::ParseDicomPropertyString ( std::string dicomPropertyString )

Parse a hex-encoded DICOM tag string and return extracted CEST parameters.

Decodes the hex-encoded string, extracts the ASCCONV parameter block, determines the sequence revision, loads the appropriate JSON parameter mapping, and populates a PropertyList with all matched CEST parameters. For CEST/WASABI sequences, frequency offsets are computed or loaded from LIST.txt. For T1 sequences, recovery times are loaded from TREC.txt.

Parameters

[in] dicomPropertyString The hex-encoded content of the Siemens private DICOM tag (0x0029, 0x1020). An empty string results in an empty PropertyList.

Returns: A PropertyList containing the extracted CEST parameters with the "CEST." prefix. Properties are also registered with the IPropertyPersistence service.

See also: ParseDicomProperty

◆ ReadListFromFile()

static std::string mitk::CustomTagParser::ReadListFromFile ( const std::string & filePath )

static

Read a space-separated list of values from a text file.

Reads all lines from the file at the given path and concatenates them into a single space-separated string. Used internally to load LIST.txt (offsets) and TREC.txt (T1 recovery times).

Parameters

[in] filePath Absolute path to the text file to read.

Returns: A string containing all values from the file separated by spaces. Returns an empty string if the file cannot be opened.

◆ SetParseStrategy()

void mitk::CustomTagParser::SetParseStrategy ( std::string parseStrategy )

Set the strategy used to determine the type of CEST data.

Parameters

[in]

parseStrategy

The parse strategy to use. Valid values are:

"Automatic" (default): auto-detect whether data is T1 or CEST/WASABI
"T1": force interpretation as T1 sequence
"CEST/WASABI": force interpretation as CEST or WASABI sequence

◆ SetRevisionMappingStrategy()

void mitk::CustomTagParser::SetRevisionMappingStrategy ( std::string revisionMappingStrategy )

Set the strategy for matching revision numbers to JSON parameter mappings.

Parameters

[in]

revisionMappingStrategy

The mapping strategy to use. Valid values are:

"Fuzzy" (default): use the closest lower or equal revision mapping
"Strict": require an exact revision match; throws if none is found

Member Data Documentation

◆ m_CESTPropertyPrefix

const std::string mitk::CustomTagParser::m_CESTPropertyPrefix

static

Prefix for all CEST-related property names ("CEST.").

Definition at line 166 of file mitkCustomTagParser.h.

◆ m_ClosestExternalRevision

std::string mitk::CustomTagParser::m_ClosestExternalRevision

protected

the closest lower revision provided as a json beside the library, empty if none found

Definition at line 190 of file mitkCustomTagParser.h.

◆ m_ClosestInternalRevision

std::string mitk::CustomTagParser::m_ClosestInternalRevision

protected

the closest lower revision provided as resource, empty if none found

Definition at line 188 of file mitkCustomTagParser.h.

◆ m_DefaultJsonString

const std::string mitk::CustomTagParser::m_DefaultJsonString

staticprotected

default revision dependent json string if none is found

Definition at line 195 of file mitkCustomTagParser.h.

◆ m_DicomDataPath

std::string mitk::CustomTagParser::m_DicomDataPath

protected

path to the dicom data

Definition at line 197 of file mitkCustomTagParser.h.

◆ m_JSONRevisionPropertyName

const std::string mitk::CustomTagParser::m_JSONRevisionPropertyName

static

Name of the property for the JSON parameter mapping revision ("CEST.revision_json").

Definition at line 163 of file mitkCustomTagParser.h.

◆ m_ParseStrategy

std::string mitk::CustomTagParser::m_ParseStrategy

protected

Should the kind of data be automatically determined or should it be parsed as a specific one.

Definition at line 199 of file mitkCustomTagParser.h.

◆ m_RevisionIndependentMapping

const std::string mitk::CustomTagParser::m_RevisionIndependentMapping

staticprotected

revision independent mapping to inject into the revision dependent json string

Definition at line 193 of file mitkCustomTagParser.h.

◆ m_RevisionMappingStrategy

std::string mitk::CustomTagParser::m_RevisionMappingStrategy

protected

How to handle parameter mapping based on absent revision jsons.

Definition at line 201 of file mitkCustomTagParser.h.

◆ m_RevisionPropertyName

const std::string mitk::CustomTagParser::m_RevisionPropertyName

static

Name of the property for the data acquisition revision ("CEST.Revision").

Definition at line 160 of file mitkCustomTagParser.h.

The documentation for this class was generated from the following file:

mitkCustomTagParser.h

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ CustomTagParser()

Member Function Documentation

◆ ExtractRevision()

◆ GetClosestLowerRevision() [1/2]

◆ GetClosestLowerRevision() [2/2]

◆ GetExternalJSONDirectory()

◆ GetExternalRevisions()

◆ GetInternalRevisions()

◆ GetOffsetString()

◆ GetRevisionAppropriateJSONString()

◆ IsT1Sequence()

◆ ParseDicomProperty()

◆ ParseDicomPropertyString()

◆ ReadListFromFile()

◆ SetParseStrategy()

◆ SetRevisionMappingStrategy()

Member Data Documentation

◆ m_CESTPropertyPrefix

◆ m_ClosestExternalRevision

◆ m_ClosestInternalRevision

◆ m_DefaultJsonString

◆ m_DicomDataPath

◆ m_JSONRevisionPropertyName

◆ m_ParseStrategy

◆ m_RevisionIndependentMapping

◆ m_RevisionMappingStrategy

◆ m_RevisionPropertyName