DCMTK Version 3.7.0 OFFIS DICOM Toolkit

Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Static Protected Attributes | List of all members
DiDisplayFunction Class Referenceabstract

Class to handle hardcopy and softcopy device characteristics file and manage display LUTs (for calibration) More...

Inheritance diagram for DiDisplayFunction:

## Public Types
enum | E_DeviceType { EDT_Monitor , EDT_Camera , EDT_Printer , EDT_Scanner }
| output device type More...

## Public Member Functions
| DiDisplayFunction (const char *filename, const E_DeviceType deviceType=EDT_Monitor, const signed int ord=-1)
| constructor, read device characteristics file. More...
| DiDisplayFunction (const double *val_tab, const unsigned long count, const Uint16 max=255, const E_DeviceType deviceType=EDT_Monitor, const signed int ord=0)
| constructor, use given array of luminance/OD values. More...
| DiDisplayFunction (const Uint16 *ddl_tab, const double *val_tab, const unsigned long count, const Uint16 max=255, const E_DeviceType deviceType=EDT_Monitor, const signed int ord=0)
| constructor, use given array of DDL and luminance/OD values. More...
| DiDisplayFunction (const double val_min, const double val_max, const unsigned long count=256, const E_DeviceType deviceType=EDT_Monitor, const signed int ord=0)
| constructor, compute luminance/OD values automatically within the specified range. More...
virtual | ~DiDisplayFunction ()
| destructor
int | isValid () const
| check whether DisplayFunction is valid More...
E_DeviceType | getDeviceType () const
| get output device type (monitor, camera, printer or scanner) More...
Uint16 | getMaxDDLValue () const
| get maximum DDL value. More...
double | getMinValue () const
| get minimum luminance/OD value from the characteristic curve. More...
double | getMaxValue () const
| get maximum luminance/OD value from the characteristic curve. More...
double | getValueforDDL (const Uint16 ddl) const
| get the luminance/OD value for a given DDL. More...
Uint16 | getDDLforValue (const double value) const
| get the DDL for a given luminance/OD value. More...
const DiDisplayLUT * | getLookupTable (const int bits, unsigned long count=0)
| create look-up table with specified number of entries More...
int | deleteLookupTable (const int bits)
| delete specified LUT More...
virtual int | writeCurveData (const char *filename, const OFBool mode=OFTrue)=0
| write curve data to a text file (abstract method) More...
double | getAmbientLightValue () const
| get (reflected) ambient light value. More...
virtual int | setAmbientLightValue (const double value)
| set (reflected) ambient light value. More...
double | getIlluminationValue () const
| get illumination value. More...
virtual int | setIlluminationValue (const double value)
| set illumination value. More...
double | getMinDensityValue () const
| get minimum optical density value "Dmin". More...
virtual int | setMinDensityValue (const double value)
| set minimum optical density value "Dmin". More...
double | getMaxDensityValue () const
| get maximum optical density value "Dmax". More...
virtual int | setMaxDensityValue (const double value)
| set maximum optical density value "Dmax". More...
double | getMinLuminanceValue () const
| get minimum luminance value "Lmin". More...
double | getMaxLuminanceValue () const
| get maximum luminance value "Lmax". More...
signed int | getPolynomialOrder () const
| get order of the polynomial curve fitting algorithm. More...
double | convertODtoLum (const double value, const OFBool useAmb=OFTrue) const
| convert the given OD value to luminance. More...

## Static Public Member Functions
static double | convertODtoLum (const double value, const double ambient, const double illum)
| convert the given OD value to luminance. More...

## Protected Member Functions
virtual DiDisplayLUT * | getDisplayLUT (unsigned long count)=0
| create display LUT with specified number of entries (abstract method) More...
int | readConfigFile (const char *filename)
| read the given device characteristics file More...
int | createSortedTable (const Uint16 *ddl_tab, const double *val_tab)
| create a sorted (by DDL) table from the given DDL and luminance/OD tables More...
double * | convertODtoLumTable (const double *od_tab, const unsigned long count, const OFBool useAmb)
| create a table with luminance values from the given OD table. More...
int | interpolateValues ()
| interpolate device characteristic curve by means of a cubic spline interpolation
int | calculateMinMax ()
| calculate minimum and maximum luminance/OD values More...
int | checkMinMaxDensity () const
| check whether Dmin and Dmax are properly specified. More...

## Protected Attributes
int | Valid
| status flag, indicating whether display function is valid
const E_DeviceType | DeviceType
| output device type (monitor, camera, printer or scanner)
unsigned long | ValueCount
| number of DDL and luminance/OD values
Uint16 | MaxDDLValue
| maximum DDL value (usually 255)
signed int | Order
| order of the polynomial curve fitting algorithm
double | AmbientLight
| (reflected) ambient light value
double | Illumination
| illumination value
double | MinDensity
| minimum optical density (-1 if unset)
double | MaxDensity
| maximum optical density (-1 if unset)
Uint16 * | DDLValue
| pointer to array of DDL values
double * | LODValue
| pointer to array of corresponding luminance/OD values
double | MinValue
| minimum luminance/OD value
double | MaxValue
| maximum luminance/OD value
DiDisplayLUT * | LookupTable [MAX_NUMBER_OF_TABLES]
| array with pointer to the different lookup tables (here: 8-16 bits)

## Static Protected Attributes
static const int | MinBits
| constant defining minimum value for number of bits for LUT input (here: 8)
static const int | MaxBits
| constant defining maximum value for number of bits for LUT input (here: 16)

## Detailed Description

Class to handle hardcopy and softcopy device characteristics file and manage display LUTs (for calibration)

## Member Enumeration Documentation

## ◆ E_DeviceType

enum DiDisplayFunction::E_DeviceType

output device type

Enumerator
EDT_Monitor | monitor (softcopy output device), values expected to be in luminance (cd/m^2)
EDT_Camera | camera (softcopy input device), values expected to be in luminance (cd/m^2)
EDT_Printer | printer (hardcopy output device), values expected to be in optical density (OD)
EDT_Scanner | scanner (hardcopy input device), values expected to be in optical density (OD)

## Constructor & Destructor Documentation

## ◆ DiDisplayFunction() [1/4]

DiDisplayFunction::DiDisplayFunction | ( | const char * | filename,
|  | const E_DeviceType | deviceType = `EDT_Monitor`,
|  | const signed int | ord = `-1`
| ) |  |

constructor, read device characteristics file.

Keywords: "max" for maximum DDL (digital driving level, required at first position) "amb" for ambient light and "lum" for illumination (both optional) "ord" for the order of the polynomial curve fitting algorithm used to interpolate the given base points (0 or absent = use cubic spline interpolation)

Parameters

  filename | name of the characteristics file (luminance/OD for each DDL)
  deviceType | type of the output device (default: monitor)
  ord | order of the polynomial curve fitting algorithm used to interpolate the given base points (-1 = use file setting, 0 = cubic spline)

## ◆ DiDisplayFunction() [2/4]

DiDisplayFunction::DiDisplayFunction | ( | const double * | val_tab,
|  | const unsigned long | count,
|  | const Uint16 | max = `255`,
|  | const E_DeviceType | deviceType = `EDT_Monitor`,
|  | const signed int | ord = `0`
| ) |  |

constructor, use given array of luminance/OD values.

UNTESTED Values must be sorted and complete (i.e. there must be an entry for each DDL). The given arrays are copied internally.

Parameters

  val_tab | pointer to array with luminance/OD values
  count | number of array elements (should be equal to 'max + 1')
  max | maximum DDL (digital driving level)
  deviceType | type of the output device (default: monitor)
  ord | order of the polynomial curve fitting algorithm used to interpolate the given base points (0 or negative = use cubic spline interpolation)

## ◆ DiDisplayFunction() [3/4]

DiDisplayFunction::DiDisplayFunction | ( | const Uint16 * | ddl_tab,
|  | const double * | val_tab,
|  | const unsigned long | count,
|  | const Uint16 | max = `255`,
|  | const E_DeviceType | deviceType = `EDT_Monitor`,
|  | const signed int | ord = `0`
| ) |  |

constructor, use given array of DDL and luminance/OD values.

UNTESTED Values will be automatically sorted and missing values will be interpolated. The given arrays are copied internally.

Parameters

  ddl_tab | pointer to array with DDL values (must be with the interval 0..max)
  val_tab | pointer to array with luminance/OD values
  count | number of array elements (2..65536)
  max | maximum DDL (digital driving level)
  deviceType | type of the output device (default: monitor)
  ord | order of the polynomial curve fitting algorithm used to interpolate the given base points (0 or negative = use cubic spline interpolation)

## ◆ DiDisplayFunction() [4/4]

DiDisplayFunction::DiDisplayFunction | ( | const double | val_min,
|  | const double | val_max,
|  | const unsigned long | count = `256`,
|  | const E_DeviceType | deviceType = `EDT_Monitor`,
|  | const signed int | ord = `0`
| ) |  |

constructor, compute luminance/OD values automatically within the specified range.

Initial values for hardcopy: "lum" = 2000, "amb" = 10, for softcopy: "amb" = 0.

Parameters

  val_min | minimum luminance/OD value
  val_max | maximum luminance/OD value
  count | number of DDLs (digital driving level, 1..65536)
  deviceType | type of the output device (default: monitor)
  ord | order of the polynomial curve fitting algorithm used to interpolate the given base points (0 or negative = use cubic spline interpolation)

## Member Function Documentation

## ◆ calculateMinMax()

int DiDisplayFunction::calculateMinMax | ( |  | ) |
| protected

calculate minimum and maximum luminance/OD values

Returns
  status, true if successful, false otherwise

## ◆ checkMinMaxDensity()

int DiDisplayFunction::checkMinMaxDensity | ( |  | ) | const
| protected

check whether Dmin and Dmax are properly specified.

report a warning message if "Dmin >= Dmax".

Returns
  status, true if successful, false otherwise

## ◆ convertODtoLum() [1/2]

static double DiDisplayFunction::convertODtoLum | ( | const double | value,
|  | const double | ambient,
|  | const double | illum
| ) |  |
| static

convert the given OD value to luminance.

This function uses the specified ambient light and illumination values.

Parameters

  value | optical density value to be converted (>= 0)
  ambient | ambient light value used for the conversion (>= 0)
  illum | illumination value used for the conversion (>= 0)

Returns
  luminance value if successful, -1 otherwise

## ◆ convertODtoLum() [2/2]

double DiDisplayFunction::convertODtoLum | ( | const double | value,
|  | const OFBool | useAmb = `OFTrue`
| ) |  | const

convert the given OD value to luminance.

This function uses the currently set ambient light and illumination values.

Parameters

  value | optical density value to be converted (>= 0)
  useAmb | use ambient light value if OFTrue

Returns
  luminance value if successful, -1 otherwise

## ◆ convertODtoLumTable()

double* DiDisplayFunction::convertODtoLumTable | ( | const double * | od_tab,
|  | const unsigned long | count,
|  | const OFBool | useAmb
| ) |  |
| protected

create a table with luminance values from the given OD table.

Uses the currently set ambient light and illumination value. The resulting luminance table has to be deleted by the caller.

Parameters

  od_tab | pointer to array with optical density values
  count | number of entries in the array
  useAmb | use ambient light value if OFTrue

Returns
  pointer to luminance table if successful, NULL otherwise

## ◆ createSortedTable()

int DiDisplayFunction::createSortedTable | ( | const Uint16 * | ddl_tab,
|  | const double * | val_tab
| ) |  |
| protected

create a sorted (by DDL) table from the given DDL and luminance/OD tables

Parameters

  ddl_tab | pointer to array with DDL values
  val_tab | pointer to array with luminance/OD values

Returns
  status, true if successful, false otherwise

## ◆ deleteLookupTable()

int DiDisplayFunction::deleteLookupTable | ( | const int | bits | ) |

delete specified LUT

Parameters

  bits | depth of input values of the LUT to be deleted

Returns
  status, true if valid, false otherwise

## ◆ getAmbientLightValue()

double DiDisplayFunction::getAmbientLightValue | ( |  | ) | const
| inline

get (reflected) ambient light value.

measured in cd/m^2.

Returns
  current ambient light value

## ◆ getDDLforValue()

Uint16 DiDisplayFunction::getDDLforValue | ( | const double | value | ) | const

get the DDL for a given luminance/OD value.

Determines the DDL from the device's characteristic curve which is mapped to the closest possible luminance/OD value. Please note that neither ambient light/illumination nor min/max density are used.

Parameters

  value | luminance/OD value to be looked up

Returns
  DDL (digital driving level) if successful, 0 otherwise

## ◆ getDeviceType()

E_DeviceType DiDisplayFunction::getDeviceType | ( |  | ) | const
| inline

get output device type (monitor, camera, printer or scanner)

Returns
  output device type

## ◆ getDisplayLUT()

virtual DiDisplayLUT* DiDisplayFunction::getDisplayLUT | ( | unsigned long | count | ) |
| protected pure virtual

create display LUT with specified number of entries (abstract method)

Parameters

  count | number of LUT entries

Returns
  pointer to created LUT if successful, NULL otherwise

Implemented in DiGSDFunction, and DiCIELABFunction.

## ◆ getIlluminationValue()

double DiDisplayFunction::getIlluminationValue | ( |  | ) | const
| inline

get illumination value.

measured in cd/m^2.

Returns
  current illumination value

## ◆ getLookupTable()

const DiDisplayLUT* DiDisplayFunction::getLookupTable | ( | const int | bits,
|  | unsigned long | count = `0`
| ) |  |

create look-up table with specified number of entries

Parameters

  bits | depth of input values
  count | number of LUT entries (default: 0 = computed automatically)

Returns
  pointer to created LUT if successful, NULL otherwise

Referenced by DiMonoOutputPixelTemplate< T1, T2, T3 >::createDisplayLUT().

## ◆ getMaxDDLValue()

Uint16 DiDisplayFunction::getMaxDDLValue | ( |  | ) | const
| inline

get maximum DDL value.

The minimum DDL value is always 0.

Returns
  maximum DDL value

## ◆ getMaxDensityValue()

double DiDisplayFunction::getMaxDensityValue | ( |  | ) | const
| inline

get maximum optical density value "Dmax".

measured in optical density (OD).

Returns
  current Dmax value or -1 if not set

## ◆ getMaxLuminanceValue()

double DiDisplayFunction::getMaxLuminanceValue | ( |  | ) | const

get maximum luminance value "Lmax".

measured in cd/m^2. value is computed from "Dmin".

Returns
  current Lmax value or -1 if Dmin not set

## ◆ getMaxValue()

double DiDisplayFunction::getMaxValue | ( |  | ) | const
| inline

get maximum luminance/OD value from the characteristic curve.

In case of a usually monotonous characteristic curve the value is equivalent to the last/first entry of the array.

Returns
  maximum luminance/OD value, 0 in case of error

## ◆ getMinDensityValue()

double DiDisplayFunction::getMinDensityValue | ( |  | ) | const
| inline

get minimum optical density value "Dmin".

measured in optical density (OD).

Returns
  current Dmin value or -1 if not set

## ◆ getMinLuminanceValue()

double DiDisplayFunction::getMinLuminanceValue | ( |  | ) | const

get minimum luminance value "Lmin".

measured in cd/m^2. value is computed from "Dmax".

Returns
  current Lmin value or -1 if Dmax not set

## ◆ getMinValue()

double DiDisplayFunction::getMinValue | ( |  | ) | const
| inline

get minimum luminance/OD value from the characteristic curve.

In case of a usually monotonous characteristic curve the value is equivalent to the first/last entry of the array.

Returns
  minimum luminance/OD value, 0 in case of error

## ◆ getPolynomialOrder()

signed int DiDisplayFunction::getPolynomialOrder | ( |  | ) | const
| inline

get order of the polynomial curve fitting algorithm.

used to interpolate the given base points.

Returns
  polynomial order (0 = use cubic spline interpolation, -1 = not specified)

## ◆ getValueforDDL()

double DiDisplayFunction::getValueforDDL | ( | const Uint16 | ddl | ) | const

get the luminance/OD value for a given DDL.

Looks up a luminance/OD value in the device's characteristic curve. Please note that neither ambient light/illumination nor min/max density are used.

Parameters

  ddl | DDL (digital driving level) to be looked up

Returns
  luminance/OD value if successful, -1 otherwise

## ◆ isValid()

int DiDisplayFunction::isValid | ( |  | ) | const
| inline

check whether DisplayFunction is valid

Returns
  status, true if valid, false otherwise

Referenced by DiMonoOutputPixelTemplate< T1, T2, T3 >::createDisplayLUT().

## ◆ readConfigFile()

int DiDisplayFunction::readConfigFile | ( | const char * | filename | ) |
| protected

read the given device characteristics file

Parameters

  filename | name of the characteristics file

Returns
  status, true if successful, false otherwise

## ◆ setAmbientLightValue()

virtual int DiDisplayFunction::setAmbientLightValue | ( | const double | value | ) |
| virtual

set (reflected) ambient light value.

measured in cd/m^2. applicable to softcopy and hardcopy devices. typical values: 0.5-5 for softcopy devices, 10 for transmissive hardcopy printer and 0 for reflective hardcopy printers.

Parameters

  value | ambient light value to be set (>= 0)

Returns
  status, true if successful, false otherwise

Reimplemented in DiGSDFunction.

## ◆ setIlluminationValue()

virtual int DiDisplayFunction::setIlluminationValue | ( | const double | value | ) |
| virtual

set illumination value.

measured in cd/m^2. applicable to hardcopy devices only. typical values: 2000 for transmissive hardcopy printer and 150 for reflective hardcopy printers.

Parameters

  value | illumination value to be set (>= 0)

Returns
  status, true if successful, false otherwise

Reimplemented in DiGSDFunction.

## ◆ setMaxDensityValue()

virtual int DiDisplayFunction::setMaxDensityValue | ( | const double | value | ) |
| virtual

set maximum optical density value "Dmax".

measured in optical density (OD). applicable to printers only. typical value: 3.0

Parameters

  value | Dmax value to be set (or < 0 to unset)

Returns
  status, true if successful (1 = Dmax set, 2 = Dmax unset), false otherwise

Reimplemented in DiGSDFunction.

## ◆ setMinDensityValue()

virtual int DiDisplayFunction::setMinDensityValue | ( | const double | value | ) |
| virtual

set minimum optical density value "Dmin".

measured in optical density (OD). applicable to printers only. typical value: 0.2

Parameters

  value | Dmin value to be set (or < 0 to unset)

Returns
  status, true if successful (1 = Dmin set, 2 = Dmin unset), false otherwise

Reimplemented in DiGSDFunction.

## ◆ writeCurveData()

virtual int DiDisplayFunction::writeCurveData | ( | const char * | filename,
|  | const OFBool | mode = `OFTrue`
| ) |  |
| pure virtual

write curve data to a text file (abstract method)

Parameters

  filename | name of the text file to which the data should be written
  mode | write CC and PSC to file if OFTrue

Returns
  status, true if successful, false otherwise

Implemented in DiGSDFunction, and DiCIELABFunction.

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

- dcmimgle/include/dcmtk/dcmimgle/didispfn.h

Generated on Mon Dec 15 2025 for DCMTK Version 3.7.0 by Doxygen 1.9.1