def convert_UI(byte_string, is_little_endian, struct_format=None):
"""Return a decoded 'UI' value.
Elements with VR of 'UI' may have a non-significant trailing null ``0x00``.
Parameters
----------
byte_string : bytes or str
The encoded 'UI' element value.
is_little_endian : bool
``True`` if the value is encoded as little endian, ``False`` otherwise.
struct_format : str, optional
Not used.
Returns
-------
uid.UID or list of uid.UID
The decoded 'UI' element value without a trailing null.
"""
# Strip off 0-byte padding for even length (if there)
if not in_py2:
byte_string = byte_string.decode(default_encoding)
if byte_string and byte_string.endswith('\0'):
byte_string = byte_string[:-1]
return MultiString(byte_string, pydicom.uid.UID)
def convert_DS_string(byte_string, is_little_endian, struct_format=None):
"""Read and return a DS value or list of values"""
if not in_py2:
byte_string = byte_string.decode(default_encoding)
# Below, go directly to DS class instance rather than factory DS,
# but need to ensure last string doesn't have blank padding (use strip())
return MultiString(byte_string.strip(), valtype=pydicom.valuerep.DSclass)
def convert_DS_string(byte_string, is_little_endian, struct_format=None):
"""Return a decoded 'DS' value.
Parameters
----------
byte_string : bytes or str
The encoded 'DS' element value.
is_little_endian : bool
``True`` if the value is encoded as little endian, ``False`` otherwise.
struct_format : str, optional
Not used.
Returns
-------
valuerep.DSfloat or valuerep.DSdecimal or list of DSfloat/DSdecimal
If :attr:`~pydicom.config.use_DS_decimal` is ``True`` then returns
:class:`~pydicom.valuerep.DSdecimal` or a :class:`list` of
``DSdecimal``, otherwise returns :class:`~pydicom.valuerep.DSfloat` or
a ``list`` of ``DSfloat``.
"""
if not in_py2:
byte_string = byte_string.decode(default_encoding)
# Below, go directly to DS class instance
# rather than factory DS, but need to
# ensure last string doesn't have
# blank padding (use strip())
return MultiString(byte_string.strip(), valtype=pydicom.valuerep.DSclass)
def convert_UI(
byte_string: bytes,
is_little_endian: bool,
struct_format: Optional[str] = None
) -> Union[pydicom.uid.UID, MutableSequence[pydicom.uid.UID]]:
"""Return a decoded 'UI' value.
Elements with VR of 'UI' may have a non-significant trailing null ``0x00``.
Parameters
----------
byte_string : bytes
The encoded 'UI' element value.
is_little_endian : bool
``True`` if the value is encoded as little endian, ``False`` otherwise.
struct_format : str, optional
Not used.
Returns
-------
uid.UID or list of uid.UID
The decoded 'UI' element value without trailing nulls or spaces.
"""
# Convert to str and remove any trailing nulls or spaces
value = byte_string.decode(default_encoding)
return MultiString(value.rstrip('\0 '), pydicom.uid.UID)
def convert_string(
byte_string: bytes,
is_little_endian: bool,
struct_format: Optional[str] = None
) -> Union[str, MutableSequence[str]]:
"""Return a decoded string VR value.
String VRs are 'AE', AS', 'CS' and optionally (depending on
:ref:`pydicom.config <api_config>`) 'DA', 'DT', and 'TM'.
Parameters
----------
byte_string : bytes
The encoded text VR element value.
is_little_endian : bool
``True`` if the value is encoded as little endian, ``False`` otherwise.
format_str : str, optional
Not used.
Returns
-------
str or MultiValue of str
The decoded value(s).
"""
return MultiString(byte_string.decode(default_encoding))
def convert_string(byte_string,
is_little_endian,
struct_format=None):
"""Read and return a string or strings"""
if not in_py2:
byte_string = byte_string.decode(default_encoding)
return MultiString(byte_string)
def convert_IS_string(
byte_string: bytes,
is_little_endian: bool,
struct_format: Optional[str] = None
) -> Union[IS, MutableSequence[IS], "numpy.int64", "numpy.ndarray"]:
"""Return a decoded 'IS' value.
.. versionchanged:: 2.0
The option to return numpy values was added.
Parameters
----------
byte_string : bytes
The encoded 'IS' element value.
is_little_endian : bool
``True`` if the value is encoded as little endian, ``False`` otherwise.
struct_format : str, optional
Not used.
Returns
-------
:class:`~pydicom.valuerep.IS` or MultiValue of them, or :class:`numpy.int64` or :class:`~numpy.ndarray` of them
If :data:`~pydicom.config.use_IS_numpy` is ``False`` (default), returns
a single :class:`~pydicom.valuerep.IS` or a list of them
If :data:`~pydicom.config.use_IS_numpy` is ``True``, returns
a single :class:`numpy.int64` or a :class:`~numpy.ndarray` of them
Raises
------
ValueError
If :data:`~pydicom.config.use_IS_numpy` is ``True`` and the string
contains non-valid characters
ImportError
If :data:`~pydicom.config.use_IS_numpy` is ``True`` and numpy is not
available
"""
num_string = byte_string.decode(default_encoding)
if config.use_IS_numpy:
if not have_numpy:
raise ImportError("use_IS_numpy set but numpy not installed")
# Check for valid characters. Numpy ignores many
regex = r'[ \\0-9\.+-]*\Z'
if re.match(regex, num_string) is None:
raise ValueError(
"IS: char(s) not in repertoire: '{}'".format(
re.sub(regex[:-2], '', num_string)
)
)
value = numpy.fromstring(num_string, dtype='i8', sep=chr(92)) # 92:'\'
if len(value) == 1: # Don't use array for one number
return cast("numpy.int64", value[0])
return cast("numpy.ndarray", value)
return MultiString(num_string, valtype=pydicom.valuerep.IS)
def convert_UI(byte_string, is_little_endian, struct_format=None):
"""Read and return a UI values or values"""
# Strip off 0-byte padding for even length (if there)
if not in_py2:
byte_string = byte_string.decode(default_encoding)
if byte_string and byte_string.endswith('\0'):
byte_string = byte_string[:-1]
return MultiString(byte_string, pydicom.uid.UID)
def convert_DS_string(byte_string, is_little_endian, struct_format=None):
"""Return a decoded 'DS' value.
.. versionchanged:: 2.0
The option to return numpy values was added.
Parameters
----------
byte_string : bytes or str
The encoded 'DS' element value.
is_little_endian : bool
``True`` if the value is encoded as little endian, ``False`` otherwise.
struct_format : str, optional
Not used.
Returns
-------
:class:`~pydicom.valuerep.DSfloat`, :class:`~pydicom.valuerep.DSdecimal`, :class:`numpy.float64`, list of DSfloat/DSdecimal or :class:`numpy.ndarray` of :class:`numpy.float64`
If :attr:`~pydicom.config.use_DS_decimal` is ``False`` (default),
returns a :class:`~pydicom.valuerep.DSfloat` or list of them
If :attr:`~pydicom.config.use_DS_decimal` is ``True``,
returns a :class:`~pydicom.valuerep.DSdecimal` or list of them
If :data:`~pydicom.config.use_DS_numpy` is ``True``,
returns a :class:`numpy.float64` or a :class:`numpy.ndarray` of them
Raises
------
ValueError
If :data:`~pydicom.config.use_DS_numpy` is ``True`` and the string
contains non-valid characters
ImportError
If :data:`~pydicom.config.use_DS_numpy` is ``True`` and numpy is not
available
"""
num_string = byte_string.decode(default_encoding)
# Below, go directly to DS class instance
# rather than factory DS, but need to
# ensure last string doesn't have
# blank padding (use strip())
if config.use_DS_numpy:
if not have_numpy:
raise ImportError("use_DS_numpy set but numpy not installed")
# Check for valid characters. Numpy ignores many
regex = r'[ \\0-9\.+eE-]*\Z'
if re.match(regex, num_string) is None:
raise ValueError("DS: char(s) not in repertoire: '{}'".format(
re.sub(regex[:-2], '', num_string)))
value = numpy.fromstring(num_string, dtype='f8', sep="\\")
if len(value) == 1: # Don't use array for one number
value = value[0]
return value
return MultiString(num_string.strip(), valtype=pydicom.valuerep.DSclass)
def convert_IS_string(byte_string, is_little_endian, struct_format=None):
"""Return a decoded 'IS' value.
Parameters
----------
byte_string : bytes or str
The encoded 'IS' element value.
is_little_endian : bool
``True`` if the value is encoded as little endian, ``False`` otherwise.
struct_format : str, optional
Not used.
Returns
-------
valuerep.IS or list of IS
The decoded value(s).
"""
byte_string = byte_string.decode(default_encoding)
return MultiString(byte_string, valtype=pydicom.valuerep.IS)
def convert_string(byte_string, is_little_endian, struct_format=None):
"""Return a decoded string VR value.
String VRs are 'AS', 'CS' and optionally (depending on
:ref:`pydicom.config <api_config>`) 'DA', 'DT', and 'TM'.
Parameters
----------
byte_string : bytes or str
The encoded text VR element value.
is_little_endian : bool
``True`` if the value is encoded as little endian, ``False`` otherwise.
struct_format : str, optional
Not used.
Returns
-------
str or list of str
The decoded value(s).
"""
byte_string = byte_string.decode(default_encoding)
return MultiString(byte_string)
def convert_IS_string(byte_string, is_little_endian, struct_format=None):
"""Read and return an IS value or list of values"""
if not in_py2:
byte_string = byte_string.decode(default_encoding)
return MultiString(byte_string, valtype=pydicom.valuerep.IS)