Element VRs and Python typesΒΆ

DICOM elements can contain anything from ASCII strings to unicode text, decimals, floats, signed and unsigned integers of different byte-depth and even encoded data. The format of the value of an element is given by its Value Representation or VR, and a list of VRs is given in the DICOM Standard in Part 5, Table 6.2-1.

So when using pydicom, what Python type should be used with a given VR to ensure that the value gets written correctly?

  • Elements of any VR:
    • Can be set as empty by using None
    • Can have their values set using their set using or stored as type from the table below
  • Non-SQ element values:
    • Can also be set using a list of their set using type - for Value Multiplicity (VM) > 1, the value will be stored as a MultiValue of their stored as type
    • However, according to the DICOM Standard, elements with VR LT, OB, OD, OF, OL, OW, ST, UN, UR and UT should never have a VM greater than 1.
  • SQ element values should be set using a list of zero or more Dataset instances.
  • To ensure AT elements are encoded correctly, their values should be set using the 8-byte integer form of the tag - such as 0x00100020 for the tag (0010,0020) - and not as a 2-tuple or 2-list.
  • LO, LT, PN, SH, ST, UC and UT elements may also be set and stored using unicode in Python 2.
VR Name Set using Stored as
AE Application Entity str str
AS Age String str str
AT Attribute Tag int int
CS Code String str str
DA Date str str or DA1
DS Decimal String str, float or int DSfloat or DSdecimal2
DT Date Time str str or DT1
FL Floating Point Single float float
FD Floating Point Double float float
IS Integer String str or int IS
LO Long String str str
LT Long Text str str
OB Other Byte bytes bytes
OD Other Double bytes bytes
OF Other Float bytes bytes
OL Other Long bytes bytes
OV Other 64-bit Very Long bytes bytes
OW Other Word bytes bytes
PN Person Name str str3 (Python 2) or PersonName3 (Python 3)
SH Short String str str
SL Signed Long int int
SQ Sequence of Items list Sequence
SS Signed Short int int
ST Short Text str str
SV Signed 64-bit Very Long int int
TM Time str str or TM1
UC Unlimited Characters str str
UI Unique Identifier (UID) str UID
UL Unsigned Long int int
UN Unknown bytes bytes
UR URI/URL str str
US Unsigned Short int int
UT Unlimited Text str str
UV Unsigned 64-bit Very Long int int
1 If config.datetime_conversion = True (default False)
2 If config.use_DS_decimal = True (default False)
3 PN element values read from file will be stored as PersonNameUnicode in Python 2