Helpers around the DICOM SEG property contract on MultiLabelSegmentation. More...

#include <mitkDICOMSegmentationPropertyHelper.h>

Classes
struct	CompletionOptions
	Synthesis options for Complete. Flags are independent and additive. More...

struct	MissingItem
	One item missing from the DICOM SEG property contract on a seg. More...

Static Public Member Functions
static std::vector< MissingItem >	Validate (const MultiLabelSegmentation *seg)
	Reports what is missing from the seg's DICOM SEG contract without mutating it. More...

static std::vector< MissingItem >	Complete (MultiLabelSegmentation *seg, const CompletionOptions &options)
	Stamps MITK-specific branding defaults and applies the opt-in synthesis flags. More...

static void	InheritPatientFromSource (MultiLabelSegmentation seg, const IPropertyProvider source, bool overwrite=true)
	Copies PatientName (0010,0010) and PatientID (0010,0020) from source to seg. More...

static void	InheritStudyFromSource (MultiLabelSegmentation seg, const IPropertyProvider source, bool overwrite=true)
	Copies StudyID (0020,0010) and StudyInstanceUID (0020,000d) from source to seg. More...

static void	InheritFrameOfReferenceFromSource (MultiLabelSegmentation seg, const IPropertyProvider source, bool overwrite=true)
	Copies FrameOfReferenceUID (0020,0052) from source to seg. More...

static std::size_t	MigrateLegacyReferenceFilesToRelation (MultiLabelSegmentation *seg)
	Migrate a legacy "referenceFiles" StringLookupTable property on seg into SegSourceImageRelationRule connections. More...

static std::string	MintSyntheticUID (const std::string &kind)
	Mint a globally unique DICOM-valid UID for a synthetic identifier. More...

static const std::string &	UnknownPatientName ()

static const std::string &	UnknownPatientID ()

static const std::string &	UnknownStudyID ()

static const std::string &	UnknownContentCreatorName ()

Detailed Description

Helpers around the DICOM SEG property contract on MultiLabelSegmentation.

Validate and Complete are deliberately split into a pure-inspection and a single-mutator pair so callers can ask "what is missing" without triggering side effects, and synthesize only at points where mutation is acceptable (typically just before write). Complete uses fill-only- if-missing semantics so that branding defaults stamped by Complete itself with default options (called from the MultiLabelSegmentation constructors) coexist with later synthesis without being overwritten by generic "UNKNOWN" placeholders.

Three-phase identity model: SEG identity tags are populated across three lifecycle moments. Each moment uses a different function with different semantics; the fragmentation is intentional.

Construction-time, automatic. Complete(seg, {}) (run by the MultiLabelSegmentation constructor) stamps class invariants (Modality, MITK branding) and mints the seg's own SeriesInstanceUID (0020,000E). Initialize(templateImage) then routes to DICOMQIPropertyHelper::DeriveDICOMSourceProperties, which copies Patient + Study UIDs + StudyID + FrameOfReferenceUID from the source. This function is shared with parametric maps via ModelFitResultHelper, which is why it lives in MitkDICOMQI.
Setup-time, explicit. mitkLabelSetImageHelper::SetupDerivedSegmentation calls SegSourceImageRelationRule::Connect plus the InheritXxxFromSource helpers with overwrite semantics, so the GUI "New Segmentation" flow can re-attach a seg to a different source than its template.
Write-time, automatic. DICOMSegmentationIO::Write calls StampSegIdentityOnSourceItem to copy the seg's identity onto dcmqi's synthetic source DcmItem so dcmqi can produce a valid SEG file. The tag list mirrors what DeriveDICOMSourceProperties produces, but the direction is opposite (seg -> source-item, not source -> seg). Not a duplicated responsibility.

See also: SegSourceImageRelationRule; MultiLabelSegmentation

Definition at line 84 of file mitkDICOMSegmentationPropertyHelper.h.

Member Function Documentation

◆ Complete()

static std::vector<MissingItem> mitk::DICOMSegmentationPropertyHelper::Complete	(	MultiLabelSegmentation *	seg,
		const CompletionOptions &	options
	)

static

Stamps MITK-specific branding defaults and applies the opt-in synthesis flags.

Called from MultiLabelSegmentation's constructors with default options to stamp the class invariants (Modality="SEG" and MITK-branded series description and content creator). Identifying tags (PatientName, PatientID, StudyID, FrameOfReferenceUID, ...) are NOT stamped unless synthesizeMissingIdentity is set, so a later Initialize(template) or InheritXxxFromSource can still adopt source values.

Never overwrites a property that is already set. Never fabricates per-instance ReferencedSOPInstanceUIDs because those would lie about data that exists in the world (unlike top-level placeholder UIDs which describe the seg itself).

Precondition: seg must be a valid pointer.

◆ InheritFrameOfReferenceFromSource()

static void mitk::DICOMSegmentationPropertyHelper::InheritFrameOfReferenceFromSource	(	MultiLabelSegmentation *	seg,
		const IPropertyProvider *	source,
		bool	overwrite = `true`
	)

static

Copies FrameOfReferenceUID (0020,0052) from source to seg.

Useful when the seg lives in the source's spatial frame, which is typical when the seg's geometry was initialized from the source. Not entailed by source-image derivation: a seg can derive from a source while living in a different frame of reference (e.g. a resampled seg).

Default semantics: overwrite. See InheritPatientFromSource.

Precondition: seg must be a valid pointer.; source must be a valid pointer.

◆ InheritPatientFromSource()

static void mitk::DICOMSegmentationPropertyHelper::InheritPatientFromSource	(	MultiLabelSegmentation *	seg,
		const IPropertyProvider *	source,
		bool	overwrite = `true`
	)

static

Copies PatientName (0010,0010) and PatientID (0010,0020) from source to seg.

Useful when the seg is derived from an image in a known patient and should appear under that patient in PACS / downstream tooling. Not entailed by establishing a source-image relation: a seg can derive from a source while declaring a different patient, but that is unusual and out of scope here.

Default semantics: overwrite. Calling InheritPatientFromSource means "treat the source's patient identity as authoritative on the seg". Pass overwrite=false to keep any values already set on the seg.

Parameters

seg	The segmentation to mutate.
source	Property provider to read the identity from.
overwrite	If true (default), overwrites existing values on the seg; if false, fills only missing slots.

Precondition: seg must be a valid pointer.; source must be a valid pointer.

◆ InheritStudyFromSource()

static void mitk::DICOMSegmentationPropertyHelper::InheritStudyFromSource	(	MultiLabelSegmentation *	seg,
		const IPropertyProvider *	source,
		bool	overwrite = `true`
	)

static

Copies StudyID (0020,0010) and StudyInstanceUID (0020,000d) from source to seg.

Useful when the seg should appear under the same study as the source in PACS. Not entailed by source-image derivation: cross-study derivations are valid DICOM but uncommon.

Default semantics: overwrite. See InheritPatientFromSource.

Precondition: seg must be a valid pointer.; source must be a valid pointer.

◆ MigrateLegacyReferenceFilesToRelation()

static std::size_t mitk::DICOMSegmentationPropertyHelper::MigrateLegacyReferenceFilesToRelation ( MultiLabelSegmentation * seg )

static

Migrate a legacy "referenceFiles" StringLookupTable property on seg into SegSourceImageRelationRule connections.

Used by the multi-label seg native-format reader as a one-way upgrade for segs saved before the property-driven DICOM SEG rework: their source-image provenance lived in a list of DICOM file paths and was consumed by the writer directly. The new writer expects rule-managed properties on the seg, so the reader loads each file via DCMTK, extracts the identifying SOP / Class / Series UIDs, groups by source series, and feeds each group to SegSourceImageRelationRule::Connect.

Files that cannot be opened are logged via MITK_WARN and skipped (a missing source file is not a hard failure: the seg still loads; subsequent DICOM SEG writes either synthesise the missing identity or emit a standalone SEG). The referenceFiles property is removed from seg only when at least one file was successfully translated AND every referenced file was resolved (zero unresolved); otherwise it is preserved so callers can retry the migration (e.g. after a network share is remounted).

No-op when seg carries no referenceFiles property, when the property's value is empty, or when seg already carries any SegSourceImageRelationRule connection.

Precondition: seg must be a valid pointer.

Returns: The number of rule connections established.

◆ MintSyntheticUID()

static std::string mitk::DICOMSegmentationPropertyHelper::MintSyntheticUID ( const std::string & kind )

static

Mint a globally unique DICOM-valid UID for a synthetic identifier.

Single chokepoint for synthesis-time UID minting so a future switch to an MITK-registered organisation root (with a dedicated "synthetic / unknown data" subnamespace) is a one-line change in the implementation without touching call sites.

Today: routes through DCMTK's dcmGenerateUniqueIdentifier under SITE_INSTANCE_UID_ROOT (OFFIS). DICOM-compliant and globally unique, but not visually identifiable as an MITK placeholder.

Parameters

kind	A short tag describing what the UID is for (e.g. "study", "series", "for", "source-instance"). Currently informational only; reserved for a future hash-derived subspace.

◆ UnknownContentCreatorName()

static const std::string& mitk::DICOMSegmentationPropertyHelper::UnknownContentCreatorName ( )

static

◆ UnknownPatientID()

static const std::string& mitk::DICOMSegmentationPropertyHelper::UnknownPatientID ( )

static

◆ UnknownPatientName()

static const std::string& mitk::DICOMSegmentationPropertyHelper::UnknownPatientName ( )

static

◆ UnknownStudyID()

static const std::string& mitk::DICOMSegmentationPropertyHelper::UnknownStudyID ( )

static

◆ Validate()

static std::vector<MissingItem> mitk::DICOMSegmentationPropertyHelper::Validate ( const MultiLabelSegmentation * seg )

static

Reports what is missing from the seg's DICOM SEG contract without mutating it.

Empty result means the seg is writable in strict mode without further synthesis.

Precondition: seg must be a valid pointer.

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

mitkDICOMSegmentationPropertyHelper.h

Classes

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ Complete()

◆ InheritFrameOfReferenceFromSource()

◆ InheritPatientFromSource()

◆ InheritStudyFromSource()

◆ MigrateLegacyReferenceFilesToRelation()

◆ MintSyntheticUID()

◆ UnknownContentCreatorName()

◆ UnknownPatientID()

◆ UnknownPatientName()

◆ UnknownStudyID()

◆ Validate()