Class representing an object of the "Segmentation IOD" or "Label Map Segmentation IOD". More...

Inheritance diagram for DcmSegmentation:

Classes
struct	LoadingFlags
	Flags for loading segmentation objects. More...

Public Member Functions
virtual	~DcmSegmentation ()
	Destructor, frees memory.
OFCondition	saveFile (const OFString &filename, const E_TransferSyntax writeXfer=EXS_LittleEndianExplicit)
	Save current object to given filename.
OFCondition	writeDataset (DcmItem &dataset)
	Write current object to given item.
OFCondition	writeConcatenation (ConcatenationCreator &cc)
	Write current object to a Concatenation.
virtual void	setCheckFGOnWrite (const OFBool doCheck)
	If enabled, functional group structure is checked before actual writing is performed in the write() method.
virtual OFBool	getCheckFGOnWrite ()
	Returns whether functional group structure is checked before actual writing is performed in the write() method.
virtual void	setValueCheckOnWrite (const OFBool doCheck)
	Set whether attribute values should be checked on writing, i.e.
virtual void	setCheckDimensionsOnWrite (const OFBool doCheck)
	If enabled, dimensions are checked before actual writing.
virtual OFBool	getCheckDimensionsOnWrite ()
	Returns whether dimensions are checked before actual writing is performed in the write() method.
virtual E_TransferSyntax	getInputTransferSyntax () const
	Get input transfer syntax.
size_t	getNumberOfFrames ()
	Get number of frames, based on the number of items in the shared functional functional groups sequence (i.e. the attribute Number of Frames) is not trusted).
DcmSegTypes::E_SegmentationType	getSegmentationType ()
	Get Segmentation Type.
DcmSegTypes::E_SegmentationFractionalType	getSegmentationFractionalType ()
	Get Fractional Segmentation Type.
size_t	getNumberOfSegments ()
	Get the Number of Segments.
virtual OFBool	check (const OFBool checkFGStructure=OFTrue)
	Perform some basic checking.
virtual FGInterface &	getFunctionalGroups ()
	Get access to functional groups.
virtual IODMultiFrameFGModule::ConcatenationInfo &	getConcatenationInfo ()
	Get reference t Concatenation information.
virtual IODGeneralEquipmentModule &	getEquipment ()
	Get General Equipment Module.
virtual IODSegmentationSeriesModule &	getSegmentationSeriesModule ()
	Get Segmentation Series Module.
virtual OFCondition	getModality (OFString &value, const signed long pos=0) const
	Get modality (overwrite from DcmIODCommon.
virtual DcmSegment *	getSegment (const Uint16 segmentNumber)
	Get segment by providing the logical segment number.
virtual const OFMap< Uint16, DcmSegment * > &	getSegments ()
	Get all segments.
virtual OFBool	getSegmentNumber (const DcmSegment *segment, size_t &segmentNumber)
	Get logical segment number by providing a pointer to a given segment.
virtual SOPInstanceReferenceMacro &	getReferencedPPS ()
	Reference to the Performed Procedure Step that led to the creation of this segmentation object.
virtual const DcmIODTypes::FrameBase *	getFrame (const size_t &frameNo)
	Get (const) frame data of a specific frame.
virtual void	getFramesForSegment (const size_t &segmentNumber, OFVector< size_t > &frameNumbers)
	Get the frame numbers that belong to a specific segment number.
virtual OFCondition	addSegment (DcmSegment *seg, Uint16 &segmentNumber)
	Add segment to segmentation object.
virtual void	setBackgroundHandlingMode (const DcmSegTypes::E_BackgroundHandling mode)
	Set the policy that governs how pixel values present in the Pixel Data but not described by an Item of the Segment Sequence ("uncovered" values) are handled when writing a Labelmap segmentation.
virtual DcmSegTypes::E_BackgroundHandling	getBackgroundHandlingMode () const
	Get the current background handling mode.
virtual OFCondition	setBackgroundPixelValue (const Uint16 value)
	Set the pixel value that is treated as background in a Labelmap segmentation.
virtual OFCondition	setBackgroundPixelValue (const Uint16 value, const CodeSequenceMacro &propertyType, const CodeSequenceMacro &propertyCategory)
	Set the background pixel value and the codes of the Background segment that is inserted for it.
virtual Uint16	getBackgroundPixelValue () const
	Get the pixel value that is treated as background (default 0).
virtual OFBool	getBackgroundSegmentNumber (Uint16 &segmentNumber)
	Get the Segment Number that is treated as background, i.e. the designated background pixel value, provided a Segment actually exists at that number.
virtual OFCondition	addForAllFrames (const FGBase &group)
	Add a functional group for all frames.
template<typename T>
OFCondition	addFrame (T pixData, const Uint16 segmentNumber, const OFVector< FGBase > &perFrameInformation)
	Add frame to segmentation object.
virtual ContentIdentificationMacro &	getContentIdentification ()
	Return reference to content content identification of this segmentation object.
virtual IODMultiframeDimensionModule &	getDimensions ()
	Return reference to multi-fame dimension module.
virtual IODICCProfileModule &	getICCProfile ()
	Return reference to ICC Profile Module.
virtual IODPaletteColorLUTModule &	getPaletteColorLUT ()
	Return reference to Palette Color Lookup Table module.
virtual OFCondition	setLossyImageCompressionFlag (const OFString &ratios, const OFString &methods, const OFBool checkValues=OFTrue)
	Set lossy compression flag of the segmentation object to "01".
virtual OFCondition	setEquipmentInfo (const IODGeneralEquipmentModule::EquipmentInfo &equipmentInfo, const OFBool checkValue=OFTrue)
	Set equipment info for this segmentation object.
virtual OFCondition	setContentIdentification (const ContentIdentificationMacro &contentIdentification, const OFBool checkValue=OFTrue)
	Set content identification info for this segmentation object.
virtual OFCondition	importFromSourceImage (DcmItem &dataset, const OFBool takeOverCharset=OFTrue)
	Import Patient, Study, and Frame of Reference level information from the given item.
virtual OFCondition	importFromSourceImage (const OFString &filename, const OFBool takeOverCharset=OFTrue)
	Import Patient, Study, and Frame of Reference level information from the given item.
Public Member Functions inherited from DcmIODImage< IODImagePixelModule< Uint16 >, IODImagePixelModule< Uint8 > >
	DcmIODImage ()
	Constructor, creates new DcmIODImage instance with integer-based pixel data.
virtual	~DcmIODImage ()
	Virtual Destructor.
IODGeneralImageModule &	getGeneralImage ()
	Get General Image Module.
IODImagePixelModuleType &	getImagePixel ()
	Get Image Pixel Module (variant).
virtual OFCondition	write (DcmItem &dataset)
	Write current common image module's attributes to DICOM dataset.
Public Member Functions inherited from DcmIODCommon
	DcmIODCommon ()
	Constructor.
	DcmIODCommon (const DcmIODCommon &rhs)
	Copy Constructor.
OFshared_ptr< IODRules >	getRules ()
	Get rules handled by this IOD.
OFshared_ptr< DcmItem >	getData ()
	Get item managed by this IOD.
IODPatientModule &	getPatient ()
	Get Patient Module.
IODPatientStudyModule &	getPatientStudy ()
	Get Patient Study Module.
IODGeneralStudyModule &	getStudy ()
	Get General Study Module.
IODGeneralEquipmentModule &	getEquipment ()
	Get General Equipment Module.
IODGeneralSeriesModule &	getSeries ()
	Get Series Module.
IODFoRModule &	getFrameOfReference ()
	Get Frame of Reference Module.
IODSOPCommonModule &	getSOPCommon ()
	Get SOP Common Module.
IODCommonInstanceReferenceModule &	getCommonInstanceReference ()
	Get Common Instance Reference Module.
virtual	~DcmIODCommon ()
	Destructor.
virtual void	createNewStudy (const OFBool clearEquipment=OFTrue)
	Create new study.
virtual void	createNewSeries (const OFBool clearFoR=OFTrue)
	Create a new series.
virtual void	createNewSOPInstance ()
	Create a new SOP instance.
virtual void	ensureInstanceUIDs (const OFBool correctInvalid=OFFalse)
	Make sure that the IOD contains a SOP Instance, Series Instance and Study Instance UID.
virtual OFCondition	importHierarchy (DcmItem &dataset, const OFBool readPatient, const OFBool readStudy, const OFBool readFoR=OFFalse, const OFBool readSeries=OFFalse, const OFBool takeOverCharset=OFTrue)
	Import common module attributes from dataset but only read Patient, Study, Series and/or Frame of Reference level portions.
virtual OFCondition	importHierarchy (const OFString &filename, const OFBool readPatient, const OFBool readStudy, const OFBool readFoR=OFFalse, const OFBool readSeries=OFFalse, const OFBool takeOverCharset=OFTrue)
	CAUTION: Parameter order (readFoR and readSeries) changed compared to the old import() function.
virtual OFBool	getValueCheckOnWrite () const
	Get whether attribute value errors will be handled as errors on writing.

Static Public Member Functions
static OFCondition	loadFile (const OFString &filename, DcmSegmentation *&segmentation, const DcmSegmentation::LoadingFlags &flags=LoadingFlags())
	Static method to load a Segmentation object from a file.
static OFCondition	loadFile (const OFFile &filename, DcmSegmentation *&segmentation, const DcmSegmentation::LoadingFlags &flags=LoadingFlags())
	Static method to load a Segmentation object from a file.
static OFCondition	loadDataset (DcmDataset &dataset, DcmSegmentation *&segmentation, const DcmSegmentation::LoadingFlags &flags=LoadingFlags())
	Static method to load a Segmentation object from a dataset object.
static OFCondition	loadConcatenation (ConcatenationLoader &cl, const OFString &concatenationUID, DcmSegmentation *&segmentation)
	Static method to load a concatenation of a DICOM Segmentation instance into a DcmSegmentation object.
static OFCondition	createBinarySegmentation (DcmSegmentation *&segmentation, const Uint16 rows, const Uint16 columns, const IODGeneralEquipmentModule::EquipmentInfo &equipmentInfo, const ContentIdentificationMacro &contentIdentification)
	Factory method to create a binary segmentation object from the minimal set of information required.
static OFCondition	createLabelmapSegmentation (DcmSegmentation *&segmentation, const Uint16 rows, const Uint16 columns, const IODGeneralEquipmentModule::EquipmentInfo &equipmentInfo, const ContentIdentificationMacro &contentIdentification, const OFBool use16Bit, const DcmSegTypes::E_SegmentationLabelmapColorModel colorModel=DcmSegTypes::SLCM_MONOCHROME2)
	Factory method to create a labelmap segmentation object from the minimal set of information required.
static OFCondition	createFractionalSegmentation (DcmSegmentation *&segmentation, const Uint16 rows, const Uint16 columns, const DcmSegTypes::E_SegmentationFractionalType fractType, const Uint16 &maxFractionalValue, const IODGeneralEquipmentModule::EquipmentInfo &equipmentInfo, const ContentIdentificationMacro &contentIdentification)
	Factory method to create a fractional segmentation object from the minimal set of information required.
static FGDerivationImage *	createDerivationImageFG (const OFVector< ImageSOPInstanceReferenceMacro > &derivationImages, const OFString &derivationDescription)
	Helps to create a valid Derivation Image Functional Group Macro The memory of the resulting functional group object has to be freed by the caller.
static CodeSequenceMacro	getBackgroundPropertyTypeCode ()
	Get the default Segmented Property Type Code that identifies the Background of a Labelmap segmentation: (DCM,125040,"Background").
static CodeSequenceMacro	getBackgroundPropertyCategoryCode ()
	Get the default Segmented Property Category Code used for the Background of a Labelmap segmentation: (SCT,309825002,"Spatial and Relational Concept").
static OFBool	isBackgroundSegment (DcmSegment *segment)
	Check whether a Segment is typed as the Background, i.e. its Segmented Property Type Code is exactly (DCM,125040,"Background").

Protected Member Functions
template<typename ImagePixel>
	DcmSegmentation (OFin_place_type_t(ImagePixel))
	Protected default constructor.
OFCondition	read (DcmItem &dataset)
	Overwrites DcmIODImage::read().
OFCondition	readWithoutPixelData (DcmItem &dataset)
	Reads dataset without pixel data.
OFCondition	writeWithSeparatePixelData (DcmItem &dataset, Uint8 *&pixData, size_t &pixDataLength)
	Writes the complete dataset without pixel data, and write pixel data separately.
OFCondition	writeWithSeparatePixelData (DcmItem &dataset, Uint16 *&pixData, size_t &pixDataLength)
	Writes the complete dataset without pixel data, and write pixel data separately Version for 16 bit pixel data.
OFCondition	insertBackgroundSegment (const Uint16 value, const CodeSequenceMacro &propertyType, const CodeSequenceMacro &propertyCategory)
	Create a Background segment (label "Background", Segment Algorithm Type MANUAL) with the given codes and add it to this segmentation at the given Labelmap pixel value via addSegment() (which replaces any existing segment at that value).
virtual void	initIODRules ()
	Initialize IOD rules.
virtual OFCondition	readSegments (DcmItem &item)
	Read segments from given item.
template<typename T>
OFCondition	writeByteBasedFrames (T *pixData)
	Write fractional frames to given pixel data buffer.
virtual OFCondition	writeBinaryFrames (Uint8 *pixData, Uint16 rows, Uint16 cols, const size_t pixDataLength)
	Write binary frames to given given pixel data buffer.
virtual OFCondition	writeSegmentationImageModule (DcmItem &dataset)
	Write Segmentation Image Module.
virtual OFCondition	writeSegments (DcmItem &item)
	Write Segments.
virtual OFCondition	writeMultiFrameFunctionalGroupsModule (DcmItem &dataset)
	Write Multi-Frame Functional Groups.
virtual OFCondition	writeMultiFrameDimensionModule (DcmItem &dataset)
	Write Multi-Frame Dimension Module.
virtual OFCondition	readFrames (DcmItem &dataset)
	Read frames.
virtual OFCondition	readPixelData (DcmElement *pixelData, const size_t numFrames, const size_t pixelsPerFrame, const Uint16 bitsAlloc)
	Read pixel data from given pixel data element.
OFCondition	getAndCheckImagePixelAttributes (DcmItem &dataset, Uint16 &allocated, Uint16 &stored, Uint16 &high, Uint16 &spp, Uint16 &pixelRep, Uint16 &rows, Uint16 &cols, Uint32 &numberOfFrames, OFString &colorModel)
	Get Image Pixel module attributes and perform some basic checking.
template<typename T>
OFCondition	addFrame (T *pixData)
	Add frame to segmentation object.
OFString	determineColorModel ()
	Determine color model.
OFBool	checkColorModel (const OFString &photometricInterpretation)
	Checks whether color model found in photometricInterpretation parameter is valid, i.e.
void	setSOPClassUIDBasedOnSegmentationType ()
	Sets the SOP Class UID based on the segmentation type, i.e.

Static Protected Member Functions
static OFCondition	createCommon (DcmSegmentation *&segmentation, const Uint16 rows, const Uint16 columns, const IODGeneralEquipmentModule::EquipmentInfo &equipmentInfo, const ContentIdentificationMacro &contentIdentification, const Uint16 bitsAllocated)
	Create those data structures common for binary and fractional segmentations.
static OFCondition	createRequiredBitDepth (DcmItem &item, DcmSegmentation *&segmentation)
	Creates segmentation object with pixel data matching required bit depths (as defined by Bits Allocated).
static OFCondition	createRequiredBitDepth (const Uint16 bitsAllocated, DcmSegmentation *&segmentation)
	Creates segmentation object with pixel data matching given bit depths.

Private Member Functions
void	rebuildSegmentsCompat () const
	Rebuild m_SegmentsCompat map from m_Segments vector (lazy compat layer).
void	clearData ()
	Clear old data.
void	collectUncoveredPixelValues (OFVector< Uint16 > &uncovered) const
	Collect the set of distinct pixel values that occur in the frame data but are not described by an Item of the Segment Sequence ("uncovered" values).
OFBool	findBackgroundSegmentNumber (Uint16 &segmentNumber) const
	Get the Segment Number of the background segment.
void	finishRead ()
	Finalize a freshly read object: set the loaded-object background handling default (BGH_Warn) and interpret the background (Pixel Padding Value, uncovered-value warnings).
OFCondition	harmonizeLabelmapBackground ()
	Apply the background handling policy and synchronize Pixel Padding Value prior to writing.
OFCondition	syncPixelPaddingValue ()
	Write Pixel Padding Value (0028,0120) into the General Equipment Module to match the current background segment, or strip it if there is no background segment or this is not a Labelmap segmentation.
void	checkAndInterpretBackgroundOnRead ()
	On reading, warn about pixel values not covered by a Segment and interpret Pixel Padding Value (0028,0120) to identify the background pixel value / background segment.
OFBool	checkPixDataLength (DcmElement *pixelData, const Uint16 rows, const Uint16 cols, const Uint16 bytesPerPixel, const Uint32 &numberOfFrames)
	Check the length of the pixel data.
OFCondition	getTotalBytesRequired (const Uint16 &rows, const Uint16 &cols, const Uint16 &bytesPerPixel, const Uint32 &numberOfFrames, size_t &bytesRequired)
	Computes the number of total bytes required for the frame data of this segmentation object.
OFCondition	readSegmentationFractionalType (DcmItem &item)
	Read Fractional Type of segmentation.
OFCondition	readSegmentationType (DcmItem &item)
	Read Segmentation Type of segmentation object.

Static Private Member Functions
static OFCondition	loadFile (DcmFileFormat &dcmff, const OFString &filename, DcmDataset *&dset, const E_TransferSyntax xfer)
	Loads file.
static OFCondition	decompress (DcmDataset &dset)
	Decompress the given dataset, if compressed in Deflated or RLE transfer syntax.

Private Attributes
IODSegmentationSeriesModule	m_SegmentationSeries
	Segmentation Series Module.
IODEnhGeneralEquipmentModule	m_EnhancedGeneralEquipmentModule
	IODEnhancedEquipmentModule.
IODMultiFrameFGModule	m_FG
	Multi-frame Functional Groups module.
IODMultiframeDimensionModule	m_DimensionModule
	Multi-frame Dimension Module.
IODPaletteColorLUTModule	m_PaletteColorLUTModule
	Palette Color LUT Module.
IODICCProfileModule	m_ICCProfileModule
	ICC Profile.
OFVector< DcmIODTypes::FrameBase * >	m_Frames
	Binary frame data.
OFBool	m_16BitPixelData
	Denotes whether 16 bit pixel data is used.
DcmSegTypes::E_SegmentationLabelmapColorModel	m_LabelmapColorModel
	Denotes in case of label maps the color model to be used (only relevant for label maps, ignored for binary and fractional segmentations).
DcmSegTypes::E_BackgroundHandling	m_BackgroundMode
	Policy for handling uncovered pixel values when writing a Labelmap segmentation (only relevant for label maps).
Uint16	m_BackgroundPixelValue
	Pixel value treated as background in Labelmap segmentations, i.e. the value reported in Pixel Padding Value (0028,0120) and (in a labelmap) the Segment Number of the background segment.
OFBool	m_BackgroundDesignated
	Whether a background has actually been designated for this Labelmap (via setBackgroundPixelValue(), interpreted from Pixel Padding Value on reading, or auto-added under BGH_AddSegment).
const OFString	m_ImageType
	Image Type: (CS, VM 2-n, Type 1), in Segmentations fixed to "DERIVED\PRIMARY".
ContentIdentificationMacro	m_ContentIdentificationMacro
	Content Identification Macro.
DcmSegTypes::E_SegmentationType	m_SegmentationType
	Segmentation Type: (CS, 1, 1).
DcmSegTypes::E_SegmentationFractionalType	m_SegmentationFractionalType
	Segmentation Fractional Type: (CS, 1, 1C) (required if FRACTIONAL).
DcmUnsignedShort	m_MaximumFractionalValue
	Maximum Fractional Value: (US, 1, 1C) (required if fractional type is FRACTIONAL).
OFVector< DcmSegment * >	m_Segments
	Segment descriptions from Segment Sequence.
size_t	m_NumSegments
	Number of non-NULL segments in m_Segments.
OFMap< Uint16, DcmSegment * >	m_SegmentsCompat
	Compatibility map returned by getSegments().
OFBool	m_SegmentsCompatDirty
	When OFTrue, m_SegmentsCompat is stale and must be rebuilt from m_Segments before the next getSegments() call.
FGInterface	m_FGInterface
	Multi-frame Functional Groups high level interface.
E_TransferSyntax	m_inputXfer
	Input transfer syntax; can be EXS_Unknown if object has been created from scratch (and not from file or dataset).

Additional Inherited Members
Public Types inherited from DcmIODImage< IODImagePixelModule< Uint16 >, IODImagePixelModule< Uint8 > >
typedef DcmIODImage	IODImage
	typedef for old compilers that do not define the type 'DcmIODImage' in derived classes.
typedef IODImagePixelVariant< OFVARIADIC_TEMPLATE_PARAMETER_PACK(T)>	IODImagePixelModuleType
	A good comment would be nice, but I have nothing in mind.

Detailed Description

Class representing an object of the "Segmentation IOD" or "Label Map Segmentation IOD".

Constructor & Destructor Documentation

◆ DcmSegmentation()

template<typename ImagePixel>

DcmSegmentation::DcmSegmentation ( OFin_place_type_t(ImagePixel) )

protected

Protected default constructor.

Library users should the factory create..() method in order to create an object from scratch

Referenced by createBinarySegmentation(), createCommon(), createFractionalSegmentation(), createLabelmapSegmentation(), createRequiredBitDepth(), createRequiredBitDepth(), loadConcatenation(), loadDataset(), loadFile(), and loadFile().

Member Function Documentation

◆ addForAllFrames()

virtual OFCondition DcmSegmentation::addForAllFrames ( const FGBase & group )

virtual

Add a functional group for all frames.

Parameters

group The group to be added as shared functional group. The

Returns: EC_Normal if adding was successful, error otherwise

References addFrame().

◆ addFrame() [1/2]

template<typename T>

OFCondition DcmSegmentation::addFrame ( T * pixData )

protected

Add frame to segmentation object.

Parameters

pixData Pixel data to be added. Length must be rows*columns bytes. Pixel data is copied so it must be freed by the caller.

Returns: EC_Normal if adding was successful, error otherwise

References DCM_SEG_MAX_FRAMES, EC_MemoryExhausted, DcmIODImage< IODImagePixelModule< Uint16 >, IODImagePixelModule< Uint8 > >::getImagePixel(), DcmIODTypes::Frame< PixelType >::getLengthInBytes(), OFCondition::good(), m_Frames, DcmIODTypes::Frame< PixelType >::m_pixData, m_SegmentationType, DcmSegUtils::packBinaryFrame(), OFVector< T >::push_back(), SG_EC_MaxFramesReached, SG_EC_UnknownSegmentationType, OFVector< T >::size(), DcmSegTypes::ST_BINARY, DcmSegTypes::ST_FRACTIONAL, DcmSegTypes::ST_LABELMAP, and DcmSegTypes::ST_UNKNOWN.

◆ addFrame() [2/2]

template<typename T>

OFCondition DcmSegmentation::addFrame	(	T *	pixData,
		const Uint16	segmentNumber,
		const OFVector< FGBase * > &	perFrameInformation )

Add frame to segmentation object.

Parameters

pixData	Pixel data to be added. Length must be rows*columns bytes. For binary segmentations (bit depth i.e. Bits Allocated/Stored=1), each byte equal to 0 will be interpreted as "not set", while every other value is interpreted as "set". For fractional segmentations the full byte is copied as is. For labelmap segmentations, the value of each byte is interpreted as the segment number. In that case the segmentNumber parameters is ignored.
segmentNumber	The logical segment number (>=1) this frame refers to. The segment identified by the segmentNumber must already exist. For labelmap segmentations, this parameter is ignored.
perFrameInformation	The functional groups that identify this frame (i.e. which are planned to be not common for all other frames). The functional groups are copied, so ownership of each group stays with the caller no matter what the method returns.

Returns: EC_Normal if adding was successful, error otherwise

References addFrame(), FGInterface::addPerFrame(), OFCondition::bad(), OFVector< T >::begin(), DCM_SEG_MAX_FRAMES, FGInterface::deletePerFrame(), EC_IllegalParameter, DcmFGTypes::EFG_SEGMENTATION, OFVector< T >::end(), getSegment(), OFCondition::good(), m_16BitPixelData, m_FGInterface, m_Frames, m_SegmentationType, DcmSegTypes::segtype2OFString(), FGSegmentation::setReferencedSegmentNumber(), SG_EC_MaxFramesReached, SG_EC_NoSuchSegment, OFVector< T >::size(), DcmSegTypes::ST_LABELMAP, and OFCondition::text().

Referenced by addForAllFrames(), addFrame(), and getAndCheckImagePixelAttributes().

◆ addSegment()

virtual OFCondition DcmSegmentation::addSegment	(	DcmSegment *	seg,
		Uint16 &	segmentNumber )

virtual

Add segment to segmentation object.

Parameters

seg The segment that should be added

segmentNumber

Depending on the type of segmentation, this parameter is handled differently:

For binary and fractional segmentations the segment number is automatically assigned and will be returned in this parameter. It is assigned from 0 onwards, i.e. the first segment added will have segment number 1, the second 2, etc.
For labelmap segmentations, the segment number is taken from this parameter and can be >= 0. This is an upsert: if the segment number is already used, the existing segment at that number is replaced (the previous one is deleted, so it is not leaked, and the total number of segments is unchanged). The maximum-segments limit therefore only applies to a genuine insertion, not to such a replacement. There is no separate remove API; clearData() resets the whole object.

Returns: EC_Normal if adding was successful, error otherwise

◆ check()

virtual OFBool DcmSegmentation::check ( const OFBool checkFGStructure = OFTrue )

virtual

Perform some basic checking.

This method is also invoked when writing the object to a DICOM dataset or file.

Note: For Labelmap segmentations, this does not verify that every pixel value in the Pixel Data is described by a Segment. That requirement (Sup 243, C.8.20.2.3.3) is enforced on the write path only (it depends on the background handling mode and may insert a Background segment); see setBackgroundHandlingMode(). A successful check() does therefore not guarantee a labelmap will write without error.

Parameters

checkFGStructure If OFTrue (default), structure of functional groups is checked, too.

Returns: OFTrue, if no errors were found, OFFalse otherwise.

◆ checkAndInterpretBackgroundOnRead()

void DcmSegmentation::checkAndInterpretBackgroundOnRead ( )

private

On reading, warn about pixel values not covered by a Segment and interpret Pixel Padding Value (0028,0120) to identify the background pixel value / background segment.

Only does work for Labelmap segmentations.

◆ checkColorModel()

OFBool DcmSegmentation::checkColorModel ( const OFString & photometricInterpretation )

protected

Checks whether color model found in photometricInterpretation parameter is valid, i.e.

MONOCHROME2, or in case of labelmaps MONOCHROME2 or PALETTE. Sets internal flag m_labelmapColorModel (for labelmaps) accordingly.

Parameters

photometricInterpretation The color model to check (e.g. MONOCHROME2, PALETTE, etc.)

Returns: OFTrue if color model is valid, OFFalse otherwise

◆ checkPixDataLength()

OFBool DcmSegmentation::checkPixDataLength	(	DcmElement *	pixelData,
		const Uint16	rows,
		const Uint16	cols,
		const Uint16	bytesPerPixel,
		const Uint32 &	numberOfFrames )

private

Check the length of the pixel data.

Parameters

pixelData	The Pixel Data element
rows	Number of rows
cols	Number of columns
bytesPerPixel	Bytes per pixel (1 for 1 or 8 bit data, or 2 for 16 bit data)
numberOfFrames	Number of frames

Returns: OFTrue if length is valid, OFFalse otherwise

◆ collectUncoveredPixelValues()

void DcmSegmentation::collectUncoveredPixelValues ( OFVector< Uint16 > & uncovered ) const

private

Collect the set of distinct pixel values that occur in the frame data but are not described by an Item of the Segment Sequence ("uncovered" values).

Only meaningful for Labelmap segmentations.

Parameters

uncovered Returns the sorted, de-duplicated uncovered pixel values

◆ createBinarySegmentation()

OFCondition DcmSegmentation::createBinarySegmentation	(	DcmSegmentation *&	segmentation,
		const Uint16	rows,
		const Uint16	columns,
		const IODGeneralEquipmentModule::EquipmentInfo &	equipmentInfo,
		const ContentIdentificationMacro &	contentIdentification )

static

Factory method to create a binary segmentation object from the minimal set of information required.

The actual segments and the frame data is added separately. The memory of the resulting Segmentation object has to be freed by the caller.

Parameters

segmentation	The resulting segmentation object if provided data is valid. Otherwise NULL is returned.
rows	Number of rows of segmentation frame data
columns	Number of rows of segmentation frame data
equipmentInfo	Equipment that is responsible for creating the segmentation. All attributes in equipmentInfo must have non-empty values.
contentIdentification	Basic content identification information

Returns: EC_Normal if creation was successful, error otherwise

References DcmSegmentation().

◆ createCommon()

OFCondition DcmSegmentation::createCommon	(	DcmSegmentation *&	segmentation,
		const Uint16	rows,
		const Uint16	columns,
		const IODGeneralEquipmentModule::EquipmentInfo &	equipmentInfo,
		const ContentIdentificationMacro &	contentIdentification,
		const Uint16	bitsAllocated )

staticprotected

Create those data structures common for binary and fractional segmentations.

Parameters

segmentation	The segmentation object created
rows	The number of rows for the segmentation
columns	The number of columns for the segmentation
equipmentInfo	Equipment information
contentIdentification	Content meta information
bitsAllocated	The number of bits allocated for the pixel data 8 for binary and fractional segmentations, 8 or 16 for labelmaps

Returns: EC_Normal if creation was successful, error otherwise

References DcmSegmentation().

◆ createDerivationImageFG()

FGDerivationImage * DcmSegmentation::createDerivationImageFG	(	const OFVector< ImageSOPInstanceReferenceMacro > &	derivationImages,
		const OFString &	derivationDescription )

static

Helps to create a valid Derivation Image Functional Group Macro The memory of the resulting functional group object has to be freed by the caller.

Parameters

derivationImages	to image SOP instances
derivationDescription	Free text describing how the derivation was achieved.

Returns: The created functional group, or NULL if not successful

◆ createFractionalSegmentation()

OFCondition DcmSegmentation::createFractionalSegmentation	(	DcmSegmentation *&	segmentation,
		const Uint16	rows,
		const Uint16	columns,
		const DcmSegTypes::E_SegmentationFractionalType	fractType,
		const Uint16 &	maxFractionalValue,
		const IODGeneralEquipmentModule::EquipmentInfo &	equipmentInfo,
		const ContentIdentificationMacro &	contentIdentification )

static

Factory method to create a fractional segmentation object from the minimal set of information required.

The actual segments and the frame data is added separately. The memory of the resulting Segmentation object has to be freed by the caller.

Parameters

segmentation	The resulting segmentation object if provided data is valid. Otherwise NULL is returned.
rows	Number of rows of segmentation frame data
columns	Number of rows of segmentation frame data
fractType	Either probability (SFT_PROBABILITY) or occupancy (SFT_OCCUPANCY)
maxFractionalValue	The value inside the frame data of this segmentation that represents 100% occupancy/probability
equipmentInfo	Equipment that is responsible for creating the segmentation. All attributes in equipmentInfo must have non-empty values.
contentIdentification	Basic content identification information

Returns: EC_Normal if creation was successful, error otherwise

References DcmSegmentation().

◆ createLabelmapSegmentation()

OFCondition DcmSegmentation::createLabelmapSegmentation	(	DcmSegmentation *&	segmentation,
		const Uint16	rows,
		const Uint16	columns,
		const IODGeneralEquipmentModule::EquipmentInfo &	equipmentInfo,
		const ContentIdentificationMacro &	contentIdentification,
		const OFBool	use16Bit,
		const DcmSegTypes::E_SegmentationLabelmapColorModel	colorModel = DcmSegTypes::SLCM_MONOCHROME2 )

static

Factory method to create a labelmap segmentation object from the minimal set of information required.

The actual segments and the frame data is added separately. The memory of the resulting Segmentation object has to be freed by the caller.

Parameters

segmentation	The resulting segmentation object if provided data is valid. Otherwise NULL is returned.
rows	Number of rows of segmentation frame data
columns	Number of rows of segmentation frame data
equipmentInfo	Equipment that is responsible for creating the segmentation. All attributes in equipmentInfo must have non-empty values.
contentIdentification	Basic content identification information
use16Bit	Denote whether to use 16 bit pixel data, i.e allow for more than 255 segments (labels) in the segmentation object (up to 65535). If OFTrue, 16 bit pixel data is used, otherwise 8 bit.
colorModel	The color model to be used for the labelmap. Default is MONOCHROME2, alternative is PALETTE.

Returns: EC_Normal if creation was successful, error otherwise

References DcmSegmentation(), and DcmSegTypes::SLCM_MONOCHROME2.

◆ createRequiredBitDepth() [1/2]

OFCondition DcmSegmentation::createRequiredBitDepth	(	const Uint16	bitsAllocated,
		DcmSegmentation *&	segmentation )

staticprotected

Creates segmentation object with pixel data matching given bit depths.

Parameters

bitsAllocated	The Bits Allocated value to use (1, 8 or 16 permitted)
segmentation	The segmentation object to create

Returns: EC_Normal if creation was successful, error otherwise

References DcmSegmentation().

◆ createRequiredBitDepth() [2/2]

OFCondition DcmSegmentation::createRequiredBitDepth	(	DcmItem &	item,
		DcmSegmentation *&	segmentation )

staticprotected

Creates segmentation object with pixel data matching required bit depths (as defined by Bits Allocated).

Parameters

item	The item to read Bits Allocated from (1, 8 or 16 bits permitted)
segmentation	The segmentation object to create

Returns: EC_Normal if creation was successful, error otherwise

References DcmSegmentation().

◆ decompress()

OFCondition DcmSegmentation::decompress ( DcmDataset & dset )

staticprivate

Decompress the given dataset, if compressed in Deflated or RLE transfer syntax.

Parameters

dset	The dataset to be decompressed

Returns: EC_Normal if decompression worked (or dataset has already been decompressed), IOD_EC_CannotDecompress otherwise

◆ determineColorModel()

OFString DcmSegmentation::determineColorModel ( )

protected

Determine color model.

The color model is always MONOCHROME2, except for labelmaps where PALETTE is permitted. This method checks whether the we have a labelmap and if returns the correct string for setting Photometric Interpretation based on desired color model setting (m_LabelmapColorModel). If unknown color model is requested, MONOCHROME2 and a warning is printed.

Returns: The color model string for Photometric Interpretation attribute.

◆ findBackgroundSegmentNumber()

OFBool DcmSegmentation::findBackgroundSegmentNumber ( Uint16 & segmentNumber ) const

private

Get the Segment Number of the background segment.

The background is the designated background value (m_BackgroundPixelValue, the "lead"); it is a background segment only if a Segment actually exists at that number.

Parameters

segmentNumber Returns the background Segment Number if found

Returns: OFTrue if a background is designated and a Segment exists at it, OFFalse otherwise

◆ finishRead()

void DcmSegmentation::finishRead ( )

private

Finalize a freshly read object: set the loaded-object background handling default (BGH_Warn) and interpret the background (Pixel Padding Value, uncovered-value warnings).

Called from read() and loadConcatenation().

◆ getAndCheckImagePixelAttributes()

OFCondition DcmSegmentation::getAndCheckImagePixelAttributes	(	DcmItem &	dataset,
		Uint16 &	allocated,
		Uint16 &	stored,
		Uint16 &	high,
		Uint16 &	spp,
		Uint16 &	pixelRep,
		Uint16 &	rows,
		Uint16 &	cols,
		Uint32 &	numberOfFrames,
		OFString &	colorModel )

protected

Get Image Pixel module attributes and perform some basic checking.

Parameters

dataset	Item to read from, usually main dataset level
allocated	Bits Allocated
stored	Bits Stored
high	High Bit
spp	Samples Per Pixel
pixelRep	Pixel Representation
rows	Rows
cols	Columns
numberOfFrames	The number of frames (as set in the dataset)
colorModel	The color model used

Returns: EC_Normal if reading/checking was successful, error otherwise

References addFrame().

◆ getBackgroundHandlingMode()

virtual DcmSegTypes::E_BackgroundHandling DcmSegmentation::getBackgroundHandlingMode ( ) const

virtual

Get the current background handling mode.

Returns: The background handling mode

◆ getBackgroundPixelValue()

virtual Uint16 DcmSegmentation::getBackgroundPixelValue ( ) const

virtual

Get the pixel value that is treated as background (default 0).

Returns: The background pixel value

◆ getBackgroundPropertyCategoryCode()

CodeSequenceMacro DcmSegmentation::getBackgroundPropertyCategoryCode ( )

static

Get the default Segmented Property Category Code used for the Background of a Labelmap segmentation: (SCT,309825002,"Spatial and Relational Concept").

Returns: The Background Segmented Property Category Code

◆ getBackgroundPropertyTypeCode()

CodeSequenceMacro DcmSegmentation::getBackgroundPropertyTypeCode ( )

static

Get the default Segmented Property Type Code that identifies the Background of a Labelmap segmentation: (DCM,125040,"Background").

Provided so clients can compare a segment's type code against the background (see also isBackgroundSegment()).

Returns: The Background Segmented Property Type Code

◆ getBackgroundSegmentNumber()

virtual OFBool DcmSegmentation::getBackgroundSegmentNumber ( Uint16 & segmentNumber )

virtual

Get the Segment Number that is treated as background, i.e. the designated background pixel value, provided a Segment actually exists at that number.

Only meaningful for Labelmap segmentations.

Parameters

segmentNumber Returns the background Segment Number if a background is designated and a Segment exists at it

Returns: OFTrue if such a background segment exists, OFFalse otherwise

◆ getCheckDimensionsOnWrite()

virtual OFBool DcmSegmentation::getCheckDimensionsOnWrite ( )

virtual

Returns whether dimensions are checked before actual writing is performed in the write() method.

Returns: OFTrue if checking is performed, OFFalse otherwise

◆ getCheckFGOnWrite()

virtual OFBool DcmSegmentation::getCheckFGOnWrite ( )

virtual

Returns whether functional group structure is checked before actual writing is performed in the write() method.

Returns: OFTrue if checking is performed, OFFalse otherwise

◆ getConcatenationInfo()

virtual IODMultiFrameFGModule::ConcatenationInfo & DcmSegmentation::getConcatenationInfo ( )

virtual

Get reference t Concatenation information.

Returns: Reference to ConcatenationInfo object

◆ getContentIdentification()

virtual ContentIdentificationMacro & DcmSegmentation::getContentIdentification ( )

virtual

Return reference to content content identification of this segmentation object.

Returns: Reference to content identification data

◆ getDimensions()

virtual IODMultiframeDimensionModule & DcmSegmentation::getDimensions ( )

virtual

Return reference to multi-fame dimension module.

Returns: Reference to multi-frame dimension module

◆ getEquipment()

virtual IODGeneralEquipmentModule & DcmSegmentation::getEquipment ( )

virtual

Get General Equipment Module.

Returns: General Equipment Module

◆ getFrame()

virtual const DcmIODTypes::FrameBase * DcmSegmentation::getFrame ( const size_t & frameNo )

virtual

Get (const) frame data of a specific frame.

Parameters

frameNo The number of the frame to get (starting with 0)

Returns: The frame requested or NULL if not existing

◆ getFramesForSegment()

virtual void DcmSegmentation::getFramesForSegment	(	const size_t &	segmentNumber,
		OFVector< size_t > &	frameNumbers )

virtual

Get the frame numbers that belong to a specific segment number.

Parameters

segmentNumber	The segment to search frames for
frameNumbers	The frame numbers belonging to that segment

◆ getFunctionalGroups()

virtual FGInterface & DcmSegmentation::getFunctionalGroups ( )

virtual

Get access to functional groups.

This is meant for reading data from functional groups that are not actively managed, i.e. made accessible by DcmSegmentation. In rare cases, however, it makes sense to access it for writing too, e.g. in order to add Stacks; use with care!

Returns: Reference to the functional groups

◆ getICCProfile()

virtual IODICCProfileModule & DcmSegmentation::getICCProfile ( )

virtual

Return reference to ICC Profile Module.

Returns: Reference to ICC Profile Module

◆ getInputTransferSyntax()

virtual E_TransferSyntax DcmSegmentation::getInputTransferSyntax ( ) const

virtual

Get input transfer syntax.

Returns EXS_Unknown if object has been created from scratch (and not from file or dataset). If the segmentation has been loaded from a concatenation, the value will be EXS_Unknown.

Returns: Input transfer syntax

◆ getModality()

virtual OFCondition DcmSegmentation::getModality	(	OFString &	value,
		const signed long	pos = 0 ) const

virtual

Get modality (overwrite from DcmIODCommon.

We always return "SEG" here)

Parameters

value	Reference to variable in which the value should be stored
pos	Index of the value to get. Not evaluated (here for consistency with other setter functions).

Returns: status, EC_Normal if successful, an error code otherwise

◆ getNumberOfFrames()

size_t DcmSegmentation::getNumberOfFrames ( )

Get number of frames, based on the number of items in the shared functional functional groups sequence (i.e. the attribute Number of Frames) is not trusted).

Note that this returns the numbers of frames present in memory. In practice (i.e. for writing later on), the number of frames must not exceed 2^31-1 (maximum value of Number of Frames attribute, enforced by writing routines).

Returns: The number of frames handled by this object

◆ getNumberOfSegments()

size_t DcmSegmentation::getNumberOfSegments ( )

Get the Number of Segments.

Note that this returns the numbers of Segments present in memory. In practice, the number of segments must not exceed 2^16-1 (enforced by writing routines).

Returns: The number of segments handled by this object

◆ getPaletteColorLUT()

virtual IODPaletteColorLUTModule & DcmSegmentation::getPaletteColorLUT ( )

virtual

Return reference to Palette Color Lookup Table module.

Returns: Reference to Palette Color Lookup Table module

◆ getReferencedPPS()

virtual SOPInstanceReferenceMacro & DcmSegmentation::getReferencedPPS ( )

virtual

Reference to the Performed Procedure Step that led to the creation of this segmentation object.

This is required if this object is created in an MPPS or GPPS workflow.

Returns: Reference to the referenced PPS object

◆ getSegment()

virtual DcmSegment * DcmSegmentation::getSegment ( const Uint16 segmentNumber )

virtual

Get segment by providing the logical segment number.

Parameters

segmentNumber The logical segment number

Returns: The segment if segment number is valid, NULL otherwise

Referenced by addFrame().

◆ getSegmentationFractionalType()

DcmSegTypes::E_SegmentationFractionalType DcmSegmentation::getSegmentationFractionalType ( )

inline

Get Fractional Segmentation Type.

Returns: Type of the segmentation, as defined by DcmSegTypes::E_SegmentationFractionalTypes (returns SFT_UNKNOWN if not fractional at all)

References m_SegmentationFractionalType.

◆ getSegmentationSeriesModule()

virtual IODSegmentationSeriesModule & DcmSegmentation::getSegmentationSeriesModule ( )

virtual

Get Segmentation Series Module.

Returns: Segmentation Series Module

◆ getSegmentationType()

DcmSegTypes::E_SegmentationType DcmSegmentation::getSegmentationType ( )

inline

Get Segmentation Type.

Returns: Type of the segmentation, as defined by DcmSegTypes::E_SegmentationType

References m_SegmentationType.

◆ getSegmentNumber()

virtual OFBool DcmSegmentation::getSegmentNumber	(	const DcmSegment *	segment,
		size_t &	segmentNumber )

virtual

Get logical segment number by providing a pointer to a given segment.

Parameters

segment	The segment to find the logical segment number for
segmentNumber	The segment number. 0 if segment could not be found.

Returns: OFTrue if segment could be found, OFFalse otherwise.

◆ getSegments()

virtual const OFMap< Uint16, DcmSegment * > & DcmSegmentation::getSegments ( )

virtual

Get all segments.

Returns: The resulting segments

◆ getTotalBytesRequired()

OFCondition DcmSegmentation::getTotalBytesRequired	(	const Uint16 &	rows,
		const Uint16 &	cols,
		const Uint16 &	bytesPerPixel,
		const Uint32 &	numberOfFrames,
		size_t &	bytesRequired )

private

Computes the number of total bytes required for the frame data of this segmentation object.

Takes into account dimensions and number of frames, as well as the type of segmentation (member variables). May file if size_t type is not able to hold the result of intermediate computations.

Parameters

rows	Number of rows of a frame
cols	Number of cols of a frame
bytesPerPixel	Bytes per pixel (use 1 for 1 or 8 bit data, or 2 for 16 bit data)
numberOfFrames	The number of frames of the object
bytesRequired	Will hold the result of the computation, if successful. Does not any padding into account.

Returns: EC_Normal if computation was possible, EC_TooManyBytesRequested otherwise.

◆ harmonizeLabelmapBackground()

OFCondition DcmSegmentation::harmonizeLabelmapBackground ( )

private

Apply the background handling policy and synchronize Pixel Padding Value prior to writing.

For Labelmap segmentations this evaluates the uncovered pixel values against the configured mode (possibly inserting a Background segment), emits the appropriate warnings/errors, and writes or strips Pixel Padding Value (0028,0120) accordingly. For non-labelmaps it only makes sure Pixel Padding Value is absent.

Returns: EC_Normal if the object may be written, an error code otherwise

◆ importFromSourceImage() [1/2]

virtual OFCondition DcmSegmentation::importFromSourceImage	(	const OFString &	filename,
		const OFBool	takeOverCharset = OFTrue )

virtual

Import Patient, Study, and Frame of Reference level information from the given item.

The method does only import Frame of Reference if Frame of Reference UID is found in the image (and no error is reported if not). The reason is that if the source images of the segmentation do have an FoR, the segmentation object must have the same one, so we must import it. If the images do not have an FoR, we must not try at all importing it. The current content of this object is not deleted before reading. If the log stream is set and valid the, the reason for any error might be obtained from the error/warning output.

Parameters

filename	Reference to DICOM dataset from which the document should be read
takeOverCharset	If OFTrue (default), Specific Character Set is taken over from imported dataset. If it's not present or empty (invalid), the attribute will not be present in this class either.

Returns: EC_Normal if successful, an error code otherwise

◆ importFromSourceImage() [2/2]

virtual OFCondition DcmSegmentation::importFromSourceImage	(	DcmItem &	dataset,
		const OFBool	takeOverCharset = OFTrue )

virtual

Import Patient, Study, and Frame of Reference level information from the given item.

The method does only import Frame of Reference if Frame of Reference (FoR) UID is found in the image (and no error is reported if not). The reason is that if the source images of the segmentation do have an FoR, the segmentation object must have the same one, so we must import it. If the images do not have an FoR, we must not try at all importing it. If the log stream is set and valid the, the reason for any error might be obtained from the error/warning output.

Parameters

dataset	Reference to DICOM dataset from which the document should be read
takeOverCharset	If OFTrue (default), Specific Character Set is taken over from imported dataset. If it's not present or empty (invalid), the attribute will not be present in this class either.

Returns: EC_Normal if successful, an error code otherwise

◆ insertBackgroundSegment()

OFCondition DcmSegmentation::insertBackgroundSegment	(	const Uint16	value,
		const CodeSequenceMacro &	propertyType,
		const CodeSequenceMacro &	propertyCategory )

protected

Create a Background segment (label "Background", Segment Algorithm Type MANUAL) with the given codes and add it to this segmentation at the given Labelmap pixel value via addSegment() (which replaces any existing segment at that value).

On failure the temporary segment is freed.

Parameters

value	The Labelmap pixel value / Segment Number for the background
propertyType	Segmented Property Type Code (usually (DCM,125040, "Background"))
propertyCategory	Segmented Property Category Code

Returns: EC_Normal if creation and insertion succeeded, an error code otherwise

◆ isBackgroundSegment()

OFBool DcmSegmentation::isBackgroundSegment ( DcmSegment * segment )

static

Check whether a Segment is typed as the Background, i.e. its Segmented Property Type Code is exactly (DCM,125040,"Background").

A code that is missing, empty, or differs from the Background code is treated as "not a Background segment".

Parameters

segment The Segment to test (NULL yields OFFalse)

Returns: OFTrue iff the segment's type code is (DCM,125040)

◆ loadConcatenation()

OFCondition DcmSegmentation::loadConcatenation	(	ConcatenationLoader &	cl,
		const OFString &	concatenationUID,
		DcmSegmentation *&	segmentation )

static

Static method to load a concatenation of a DICOM Segmentation instance into a DcmSegmentation object.

Parameters

cl	The ConcatenationLoader instance to be used. Must be configured so that load() can be called.
concatenationUID	The Concatenation UID identifying the Concatenation within the Concatenations know to ConcatenationLoader cl.
segmentation	The resulting Segmentation object, if loading was successful

Returns: EC_Normal if loading was successful, error otherwise

References DcmSegmentation().

◆ loadDataset()

OFCondition DcmSegmentation::loadDataset	(	DcmDataset &	dataset,
		DcmSegmentation *&	segmentation,
		const DcmSegmentation::LoadingFlags &	flags = LoadingFlags() )

static

Static method to load a Segmentation object from a dataset object.

The memory of the resulting Segmentation object has to be freed by the caller.

Parameters

dataset	The dataset to read from
segmentation	The resulting segmentation object. NULL if dataset could not be read successfully.
flags	Flags to configure the loading of the segmentation object

Returns: EC_Normal if reading was successful, error otherwise

References DcmSegmentation().

◆ loadFile() [1/3]

OFCondition DcmSegmentation::loadFile	(	const OFFile &	filename,
		DcmSegmentation *&	segmentation,
		const DcmSegmentation::LoadingFlags &	flags = LoadingFlags() )

static

Static method to load a Segmentation object from a file.

The memory of the resulting Segmentation object has to be freed by the caller.

Parameters

filename	The file to read from
segmentation	The resulting segmentation object. NULL if dataset could not be read successfully.
flags	Flags to configure the loading of the segmentation object

Returns: EC_Normal if reading was successful, error otherwise

References DcmSegmentation().

◆ loadFile() [2/3]

OFCondition DcmSegmentation::loadFile	(	const OFString &	filename,
		DcmSegmentation *&	segmentation,
		const DcmSegmentation::LoadingFlags &	flags = LoadingFlags() )

static

Static method to load a Segmentation object from a file.

The memory of the resulting Segmentation object has to be freed by the caller.

Parameters

filename	The file to read from
segmentation	The resulting segmentation object. NULL if dataset could not be read successfully.
flags	Flags to configure the loading of the segmentation object

Returns: EC_Normal if reading was successful, error otherwise

References DcmSegmentation().

◆ loadFile() [3/3]

OFCondition DcmSegmentation::loadFile	(	DcmFileFormat &	dcmff,
		const OFString &	filename,
		DcmDataset *&	dset,
		const E_TransferSyntax	xfer )

staticprivate

Loads file.

Parameters

dcmff	The file format to load into
filename	The filename of the file to load
dset	Pointer to dataset after loading
xfer	Transfer syntax to use for reading (if EXS_Unknown,the default, auto detection is used)

Returns: EC_Normal if loading was successful, error otherwise

◆ read()

OFCondition DcmSegmentation::read ( DcmItem & dataset )

protectedvirtual

Overwrites DcmIODImage::read().

Parameters

dataset The dataset to read from

Returns: EC_Normal if reading succeeded, error otherwise

Reimplemented from DcmIODImage< IODImagePixelModule< Uint16 >, IODImagePixelModule< Uint8 > >.

◆ readFrames()

virtual OFCondition DcmSegmentation::readFrames ( DcmItem & dataset )

protectedvirtual

Read frames.

Parameters

dataset Item to read from, usually main dataset level

Returns: EC_Normal if reading was successful, error otherwise

◆ readPixelData()

virtual OFCondition DcmSegmentation::readPixelData	(	DcmElement *	pixelData,
		const size_t	numFrames,
		const size_t	pixelsPerFrame,
		const Uint16	bitsAlloc )

protectedvirtual

Read pixel data from given pixel data element.

Parameters

pixelData	The pixel data element to read from
numFrames	The number of frames expected in the pixel data element
pixelsPerFrame	The number of pixels per frame (rows*columns)
bitsAlloc	Bits Allocated value (1, 8 or 16)

Returns: EC_Normal if reading was successful, error otherwise

◆ readSegmentationFractionalType()

OFCondition DcmSegmentation::readSegmentationFractionalType ( DcmItem & item )

private

Read Fractional Type of segmentation.

Parameters

item	The item to read from

Returns: EC_Normal if type could be read, EC_TagNotFound if tag is not present, error otherwise

◆ readSegmentationType()

OFCondition DcmSegmentation::readSegmentationType ( DcmItem & item )

private

Read Segmentation Type of segmentation object.

Parameters

item	The item to read from

Returns: EC_Normal if type could be read, EC_TagNotFound if tag is not present, error otherwise

◆ readSegments()

virtual OFCondition DcmSegmentation::readSegments ( DcmItem & item )

protectedvirtual

Read segments from given item.

Parameters

item	The item to read from

Returns: EC_Normal if reading was successful, error otherwise

◆ readWithoutPixelData()

OFCondition DcmSegmentation::readWithoutPixelData ( DcmItem & dataset )

protected

Reads dataset without pixel data.

Parameters

dataset The dataset to read from

Returns: EC_Normal if reading succeeded, error otherwise

◆ saveFile()

OFCondition DcmSegmentation::saveFile	(	const OFString &	filename,
		const E_TransferSyntax	writeXfer = EXS_LittleEndianExplicit )

Save current object to given filename.

Parameters

filename	The file to write to
writeXfer	The transfer syntax to be used

Returns: EC_Normal if writing was successful, error otherwise.

References EXS_LittleEndianExplicit.

◆ setBackgroundHandlingMode()

virtual void DcmSegmentation::setBackgroundHandlingMode ( const DcmSegTypes::E_BackgroundHandling mode )

virtual

Set the policy that governs how pixel values present in the Pixel Data but not described by an Item of the Segment Sequence ("uncovered" values) are handled when writing a Labelmap segmentation.

See DcmSegTypes::E_BackgroundHandling for the available modes. The default is DcmSegTypes::BGH_AddSegment for objects created from scratch via the factory API, and DcmSegTypes::BGH_Warn for objects loaded from a file or dataset. Only relevant for Labelmap segmentations.

Parameters

mode	The background handling mode to use

◆ setBackgroundPixelValue() [1/2]

virtual OFCondition DcmSegmentation::setBackgroundPixelValue ( const Uint16 value )

virtual

Set the pixel value that is treated as background in a Labelmap segmentation.

This is the value reported in Pixel Padding Value (0028,0120); in a labelmap it equals the Segment Number of the background segment. The default is 0. Calling this designates the background (the single source of truth, the "lead"); the Pixel Padding Value element is derived from it when writing, never written here, so it cannot go stale.

As a side effect, a Background segment (Segmented Property Category and Type Code (DCM,125040,"Background"), label "Background", Segment Algorithm Type MANUAL) is inserted immediately at this value. If a Background segment already exists there, only its codes are refreshed (re-designating the same value preserves any other customizations). It is an error to designate a value already occupied by a non-Background segment. The created segment can be further customized via getSegment(value) (e.g. label, Recommended Display CIELab Value, algorithm). Only a single Background segment is kept: changing the background value removes the previously created Background segment and inserts a new one at the new value. The Pixel Data is not modified, so any pixels still holding the old background value become uncovered (handled per the background handling mode on writing).

This method (or a Pixel Padding Value read from a file, see read()) is the way to designate a background: a Background-typed segment merely inserted via addSegment() is not auto-detected as the background. Even without calling this method, a Background segment may still be added automatically on writing if the (default) background value occurs in the Pixel Data without a segment (see setBackgroundHandlingMode(), DcmSegTypes::BGH_AddSegment).

Parameters

value The background pixel value

Returns: EC_Normal if successful, an error code otherwise (e.g. if a non-background segment already exists at that value)

◆ setBackgroundPixelValue() [2/2]

virtual OFCondition DcmSegmentation::setBackgroundPixelValue	(	const Uint16	value,
		const CodeSequenceMacro &	propertyType,
		const CodeSequenceMacro &	propertyCategory )

virtual

Set the background pixel value and the codes of the Background segment that is inserted for it.

Behaves like setBackgroundPixelValue(Uint16) but uses the given Segmented Property Type and Category Code instead of the default Category (SCT,309825002,"Spatial and Relational Concept") and Type (DCM,125040,"Background"). Since the background is tracked by its pixel value (the lead), not by the type code, the type code may be overridden freely without losing the ability to recognize the background. If a Background segment already exists at the value, its codes are refreshed in place with the ones given here (re-designating the same value to change its codes therefore takes effect).

Parameters

value	The background pixel value
propertyType	Segmented Property Type Code for the Background segment
propertyCategory	Segmented Property Category Code for the Background segment

Returns: EC_Normal if successful, an error code otherwise

◆ setCheckDimensionsOnWrite()

virtual void DcmSegmentation::setCheckDimensionsOnWrite ( const OFBool doCheck )

virtual

If enabled, dimensions are checked before actual writing.

This can be very time-consuming if many frames are present. Disabling should only be done if the user knows that the functional groups are valid, wants to to adapt the functional groups manually after calling write() or knows what he's doing otherwise.
Per default, checking is enabled.

Parameters

doCheck If OFTrue, checking will be performed. If OFFalse, no checks are performed.

◆ setCheckFGOnWrite()

virtual void DcmSegmentation::setCheckFGOnWrite ( const OFBool doCheck )

virtual

If enabled, functional group structure is checked before actual writing is performed in the write() method.

Checking might be time consuming on functional groups with many frames, though disabling might result in invalid functional group structures. Disabling should only be done if the user knows that the functional groups are valid, wants to to adapt the functional groups manually after calling write() or knows what he's doing otherwise.
Per default, checking is enabled.

Parameters

doCheck If OFTrue, checking will be performed. If OFFalse, no checks are performed.

◆ setContentIdentification()

virtual OFCondition DcmSegmentation::setContentIdentification	(	const ContentIdentificationMacro &	contentIdentification,
		const OFBool	checkValue = OFTrue )

virtual

Set content identification info for this segmentation object.

Parameters

contentIdentification	The content identification of this segmentation
checkValue	If OFTrue, the data provided is checked for validity (as possible)

Returns: EC_Normal if content identification could be set correctly, OFFalse otherwise

◆ setEquipmentInfo()

virtual OFCondition DcmSegmentation::setEquipmentInfo	(	const IODGeneralEquipmentModule::EquipmentInfo &	equipmentInfo,
		const OFBool	checkValue = OFTrue )

virtual

Set equipment info for this segmentation object.

Parameters

equipmentInfo	The description of the equipment used to create this segmentation
checkValue	If OFTrue, the data provided is checked for validity

Returns: EC_Normal if equipment information could be set successfully, error otherwise

◆ setLossyImageCompressionFlag()

virtual OFCondition DcmSegmentation::setLossyImageCompressionFlag	(	const OFString &	ratios,
		const OFString &	methods,
		const OFBool	checkValues = OFTrue )

virtual

Set lossy compression flag of the segmentation object to "01".

If one of the source images of this segmentation has undergone lossy compression then this function should be called.

Parameters

ratios	Compression ratios (separated by backslash) of the applied lossy compression steps. Only one value (and no backslash) if only one step was performed.
methods	Methods (separated by backslash) of the applied lossy compression steps. Only one value (and no backslash) if only one step was performed.
checkValues	If OFTrue, the data provided is checked for validity

Returns: EC_Normal if lossy compression info could be set, error code otherwise

◆ setSOPClassUIDBasedOnSegmentationType()

void DcmSegmentation::setSOPClassUIDBasedOnSegmentationType ( )

protected

Sets the SOP Class UID based on the segmentation type, i.e.

whether it is a binary or fractional (Segmentation Storage SOP Class) or a labelmap segmentation (Labelmap Segmentation Storage SOP Class). The SOP Class UID is set to the following values: If the segmentation type is unknown, the SOP Class UID is set to Segmentation Storage SOP Class as well but a warning is printed.

◆ setValueCheckOnWrite()

virtual void DcmSegmentation::setValueCheckOnWrite ( const OFBool doCheck )

virtual

Set whether attribute values should be checked on writing, i.e.

if writing should fail if attribute values violate their VR, VM, character set or value length. A missing but required value is always considered an error, independent of this setting. If set to OFFalse, writing will always succeed, even if attribute value constraints are violated. A warning instead of an error will be printed to the logger.

Parameters

doCheck If OFTrue, attribute value errors are handled as errors on writing, if OFFalse any errors are ignored.

Reimplemented from DcmIODImage< IODImagePixelModule< Uint16 >, IODImagePixelModule< Uint8 > >.

◆ syncPixelPaddingValue()

OFCondition DcmSegmentation::syncPixelPaddingValue ( )

private

Write Pixel Padding Value (0028,0120) into the General Equipment Module to match the current background segment, or strip it if there is no background segment or this is not a Labelmap segmentation.

Returns: EC_Normal if successful, an error code otherwise

◆ writeBinaryFrames()

virtual OFCondition DcmSegmentation::writeBinaryFrames	(	Uint8 *	pixData,
		Uint16	rows,
		Uint16	cols,
		const size_t	pixDataLength )

protectedvirtual

Write binary frames to given given pixel data buffer.

Parameters

pixData	The filled pixel data buffer returned by the method
rows	Number of rows in frame
cols	Number of columns in frame
pixDataLength	The length of buffer in pixData (in bytes) returned by this method.

Returns: EC_Normal if writing was successful, error otherwise

◆ writeByteBasedFrames()

template<typename T>

OFCondition DcmSegmentation::writeByteBasedFrames ( T * pixData )

protected

Write fractional frames to given pixel data buffer.

Parameters

pixData The filled pixel data buffer returned by the method

Returns: EC_Normal if writing was successful, error otherwise

◆ writeConcatenation()

OFCondition DcmSegmentation::writeConcatenation ( ConcatenationCreator & cc )

Write current object to a Concatenation.

Parameters

cc	The Concatenation Creator object to be used. Must be configured so that writeNextInstance() is ready to be called.

Returns: EC_Normal if writing was successful, error otherwise.

◆ writeDataset()

OFCondition DcmSegmentation::writeDataset ( DcmItem & dataset )

Write current object to given item.

The object's attributes are written into the item (merged); pre-existing, unrelated attributes already present in the item are not removed. In particular, attributes this object decides not to write (e.g. Pixel Padding Value for a non-Labelmap object) are not stripped from the item if a caller put them there beforehand. Pass a fresh item if exact contents are required.

Parameters

dataset The item to write to

Returns: EC_Normal if writing was successful, error otherwise.

◆ writeMultiFrameDimensionModule()

virtual OFCondition DcmSegmentation::writeMultiFrameDimensionModule ( DcmItem & dataset )

protectedvirtual

Write Multi-Frame Dimension Module.

Parameters

dataset The item to write to, usually main dataset level

Returns: EC_Normal if writing was successful, error otherwise

◆ writeMultiFrameFunctionalGroupsModule()

virtual OFCondition DcmSegmentation::writeMultiFrameFunctionalGroupsModule ( DcmItem & dataset )

protectedvirtual

Write Multi-Frame Functional Groups.

Parameters

dataset The item to write to, usually main dataset level

Returns: EC_Normal if writing was successful, error otherwise

◆ writeSegmentationImageModule()

virtual OFCondition DcmSegmentation::writeSegmentationImageModule ( DcmItem & dataset )

protectedvirtual

Write Segmentation Image Module.

Parameters

dataset The item to write to, usually main dataset level

Returns: EC_Normal if writing was successful, error otherwise

◆ writeSegments()

virtual OFCondition DcmSegmentation::writeSegments ( DcmItem & item )

protectedvirtual

Write Segments.

Parameters

item	The item to write to

Returns: EC_Normal if writing was successful, error otherwise

◆ writeWithSeparatePixelData() [1/2]

OFCondition DcmSegmentation::writeWithSeparatePixelData	(	DcmItem &	dataset,
		Uint16 *&	pixData,
		size_t &	pixDataLength )

protected

Writes the complete dataset without pixel data, and write pixel data separately Version for 16 bit pixel data.

Parameters

dataset	The dataset to write to
pixData	Buffer for pixel data to write to
pixDataLength	Length of pixData buffer

Returns: EC_Normal if writing succeeded, error otherwise

◆ writeWithSeparatePixelData() [2/2]

OFCondition DcmSegmentation::writeWithSeparatePixelData	(	DcmItem &	dataset,
		Uint8 *&	pixData,
		size_t &	pixDataLength )

protected

Writes the complete dataset without pixel data, and write pixel data separately.

Version for 8 bit pixel data.

Parameters

dataset	The dataset to write to
pixData	Buffer for pixel data to write to
pixDataLength	Length of pixData buffer

Returns: EC_Normal if writing succeeded, error otherwise

Member Data Documentation

◆ m_BackgroundDesignated

OFBool DcmSegmentation::m_BackgroundDesignated

private

Whether a background has actually been designated for this Labelmap (via setBackgroundPixelValue(), interpreted from Pixel Padding Value on reading, or auto-added under BGH_AddSegment).

If OFFalse, m_BackgroundPixelValue is just the default and no Pixel Padding Value is written. Default OFFalse.

◆ m_BackgroundMode

DcmSegTypes::E_BackgroundHandling DcmSegmentation::m_BackgroundMode

private

Policy for handling uncovered pixel values when writing a Labelmap segmentation (only relevant for label maps).

Default BGH_AddSegment for objects created from scratch; the read path lowers it to BGH_Warn.

◆ m_BackgroundPixelValue

Uint16 DcmSegmentation::m_BackgroundPixelValue

private

Pixel value treated as background in Labelmap segmentations, i.e. the value reported in Pixel Padding Value (0028,0120) and (in a labelmap) the Segment Number of the background segment.

Default 0. Only meaningful when m_BackgroundDesignated is OFTrue. Together with m_BackgroundDesignated this is the single source of truth ("the lead") for the background; the Pixel Padding Value element and the Background segment are derived from it on writing.

◆ m_inputXfer

E_TransferSyntax DcmSegmentation::m_inputXfer

private

Input transfer syntax; can be EXS_Unknown if object has been created from scratch (and not from file or dataset).

If the segmentation has been loaded from a concatenation, the value will be EXS_Unknown.

◆ m_Segments

OFVector<DcmSegment*> DcmSegmentation::m_Segments

private

Segment descriptions from Segment Sequence.

Indexed by Segment Number (segment N at index N). For binary/fractional segmentations, index 0 is unused (NULL). For Labelmaps, the Segment Number is the label value, i.e. the pixel value used in the pixel data to denote the segment.

◆ m_SegmentsCompat

OFMap<Uint16, DcmSegment*> DcmSegmentation::m_SegmentsCompat

mutableprivate

Compatibility map returned by getSegments().

Built lazily from m_Segments when m_SegmentsCompatDirty is OFTrue, so that callers of the public OFMap-based API are unaffected by the internal switch to OFVector. Declared mutable (together with the dirty flag below) because rebuilding the cache does not change the logical state of the object, only its internal representation, and must be possible from the const rebuildSegmentsCompat() helper.

◆ m_SegmentsCompatDirty

OFBool DcmSegmentation::m_SegmentsCompatDirty

mutableprivate

When OFTrue, m_SegmentsCompat is stale and must be rebuilt from m_Segments before the next getSegments() call.

Set to OFTrue by any operation that mutates m_Segments (addSegment, readSegments, clearData); cleared by rebuildSegmentsCompat(). Mutable for the same reason as m_SegmentsCompat (see above).

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

dcmseg/include/dcmtk/dcmseg/segdoc.h

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ DcmSegmentation()

Member Function Documentation

◆ addForAllFrames()

◆ addFrame() [1/2]

◆ addFrame() [2/2]

◆ addSegment()

◆ check()

◆ checkAndInterpretBackgroundOnRead()

◆ checkColorModel()

◆ checkPixDataLength()

◆ collectUncoveredPixelValues()

◆ createBinarySegmentation()

◆ createCommon()

◆ createDerivationImageFG()

◆ createFractionalSegmentation()

◆ createLabelmapSegmentation()

◆ createRequiredBitDepth() [1/2]

◆ createRequiredBitDepth() [2/2]

◆ decompress()

◆ determineColorModel()

◆ findBackgroundSegmentNumber()

◆ finishRead()

◆ getAndCheckImagePixelAttributes()

◆ getBackgroundHandlingMode()

◆ getBackgroundPixelValue()

◆ getBackgroundPropertyCategoryCode()

◆ getBackgroundPropertyTypeCode()

◆ getBackgroundSegmentNumber()

◆ getCheckDimensionsOnWrite()

◆ getCheckFGOnWrite()

◆ getConcatenationInfo()

◆ getContentIdentification()

◆ getDimensions()

◆ getEquipment()

◆ getFrame()

◆ getFramesForSegment()

◆ getFunctionalGroups()

◆ getICCProfile()

◆ getInputTransferSyntax()

◆ getModality()

◆ getNumberOfFrames()

◆ getNumberOfSegments()

◆ getPaletteColorLUT()

◆ getReferencedPPS()

◆ getSegment()

◆ getSegmentationFractionalType()

◆ getSegmentationSeriesModule()

◆ getSegmentationType()

◆ getSegmentNumber()

◆ getSegments()

◆ getTotalBytesRequired()

◆ harmonizeLabelmapBackground()

◆ importFromSourceImage() [1/2]

◆ importFromSourceImage() [2/2]

◆ insertBackgroundSegment()

◆ isBackgroundSegment()

◆ loadConcatenation()

◆ loadDataset()

◆ loadFile() [1/3]

◆ loadFile() [2/3]

◆ loadFile() [3/3]

◆ read()

◆ readFrames()

◆ readPixelData()

◆ readSegmentationFractionalType()

◆ readSegmentationType()

◆ readSegments()

◆ readWithoutPixelData()

◆ saveFile()