ENH: Add some conversions for DICOM value

Adds conversions between DICOM 'TM' value representation and
seconds past midnight, as well as between 'AS' value representation
and years of age.

Author: moloney

nibabel/nicom/tests/test_utils.py

@@ -10,7 +10,8 @@
                         assert_equal, assert_not_equal)
 
 
-from ..utils import find_private_section
+from ..utils import (find_private_section, seconds_to_tm, tm_to_seconds,
+                     as_to_years, years_to_as)
 
 from .test_dicomwrappers import (have_dicom, dicom_test,
                                  IO_DATA_PATH, DATA, DATA_PHILIPS)
@@ -67,3 +68,34 @@ def test_find_private_section_real():
     assert_equal(find_private_section(ds, 0x11, 'near section'), 0x1300)
     ds.add_new((0x11, 0x15), 'LO', b'far section')
     assert_equal(find_private_section(ds, 0x11, 'far section'), 0x1500)
+
+
+def test_tm_to_seconds():
+    for str_val in ('', '1', '111', '11111', '111111.', '1111111', '1:11',
+                    ' 111'):
+        assert_raises(ValueError, tm_to_seconds, str_val)
+    assert_almost_equal(tm_to_seconds('01'), 60*60)
+    assert_almost_equal(tm_to_seconds('0101'), 61*60)
+    assert_almost_equal(tm_to_seconds('010101'), 61*60 + 1)
+    assert_almost_equal(tm_to_seconds('010101.001'), 61*60 + 1.001)
+    assert_almost_equal(tm_to_seconds('01:01:01.001'), 61*60 + 1.001)
+
+
+def test_tm_rt():
+    for tm_val in ('010101.00000', '010101.00100', '122432.12345'):
+        assert_equal(tm_val, seconds_to_tm(tm_to_seconds(tm_val)))
+
+
+def test_as_to_years():
+    assert_equal(as_to_years('1'), 1.0)
+    assert_equal(as_to_years('1Y'), 1.0)
+    assert_equal(as_to_years('53'), 53.0)
+    assert_equal(as_to_years('53Y'), 53.0)
+    assert_almost_equal(as_to_years('2M'), 2. / 12.)
+    assert_almost_equal(as_to_years('2D'), 2. / 365.)
+    assert_almost_equal(as_to_years('2W'), 2. * (7. / 365.))
+
+
+def test_as_rt():
+    for as_val in ('1Y', '53Y', '2M', '2W', '2D'):
+        assert_equal(as_val, years_to_as(as_to_years(as_val)))

nibabel/nicom/utils.py

@@ -2,6 +2,8 @@
 """
 from __future__ import division, print_function, absolute_import
 
+import re, string
+
 from ..py3k import asstr
 
 
@@ -51,3 +53,138 @@ def find_private_section(dcm_data, group_no, creator):
             if creator == name:
                 return elno * 0x100
     return None
+
+
+def tm_to_seconds(time_str):
+    '''Convert a DICOM time value (value representation of 'TM') to the number
+    of seconds past midnight.
+
+    Parameters
+    ----------
+    time_str : str
+        The string value from the DICOM element
+
+    Returns
+    -------
+    sec_past_midnight : float
+        The number of seconds past midnight
+    '''
+    # Allow trailing white space
+    time_str = time_str.rstrip()
+
+    # Allow ACR/NEMA style format which includes colons between hours/minutes
+    # and minutes/seconds
+    colons = [x.start() for x in re.finditer(':', time_str)]
+    if len(colons) > 0:
+        if colons not in ([2], [2, 5]):
+            raise ValueError("Invalid use of colons in 'TM' VR")
+        time_str = time_str.replace(':', '')
+
+    # Make sure the string length is valid
+    str_len = len(time_str)
+    is_valid = str_len > 0
+    if str_len <= 6:
+        # If there are six or less chars, there should be an even number
+        if str_len % 2 != 0:
+            is_valid = False
+    else:
+        # If there are more than six chars, the seventh position should be
+        # a decimal followed by at least one digit
+        if str_len == 7 or time_str[6] != '.':
+            is_valid = False
+    if not is_valid:
+        raise ValueError("Invalid number of digits for 'TM' VR")
+
+    # Make sure we don't have leading white space
+    if time_str[0] in string.whitespace:
+        raise ValueError("Leading whitespace not allowed in 'TM' VR")
+
+    # The minutes and seconds are optional
+    result = int(time_str[:2]) * 3600
+    if str_len > 2:
+        result += int(time_str[2:4]) * 60
+    if str_len > 4:
+        result += float(time_str[4:])
+
+    return float(result)
+
+
+def seconds_to_tm(seconds):
+    '''Convert a float representing seconds past midnight into DICOM TM value
+
+    Parameters
+    ----------
+    seconds : float
+        Number of seconds past midnights
+
+    Returns
+    -------
+    tm : str
+        String suitable for use as value in DICOM element with VR of 'TM'
+    '''
+    hours = seconds // 3600
+    seconds -= hours * 3600
+    minutes = seconds // 60
+    seconds -= minutes * 60
+    res = '%02d%02d%08.5f' % (hours, minutes, seconds)
+    return res
+
+
+def as_to_years(age_str):
+    '''Convert a DICOM age value (value representation of 'AS') to the age in
+    years.
+
+    Parameters
+    ----------
+    age_str : str
+        The string value from the DICOM element
+
+    Returns
+    -------
+    age : float
+        The age of the subject in years
+    '''
+    age_str = age_str.strip()
+    if age_str[-1] == 'Y':
+        return float(age_str[:-1])
+    elif age_str[-1] == 'M':
+        return float(age_str[:-1]) / 12
+    elif age_str[-1] == 'W':
+        return float(age_str[:-1]) / (365. / 7)
+    elif age_str[-1] == 'D':
+        return float(age_str[:-1]) / 365
+    else:
+        return float(age_str)
+
+
+def years_to_as(years):
+    '''Convert float representing age in years to DICOM 'AS' value
+
+    Parameters
+    ----------
+    years : float
+        The years of age
+
+    Returns
+    -------
+    as : str
+        String suitable for use as value in DICOM element with VR of 'AS'
+    '''
+    if years == round(years):
+        return '%dY' % years
+
+   # Choose how to represent the age (years, months, weeks, or days)
+    conversions = (('Y', 1), ('M', 12), ('W', (365. / 7)), ('D', 365))
+    # Try all the conversions, ignore ones that have more than three digits
+    # which is the limit for the AS value representation, or where they round
+    # to zero
+    results = [(years * x[1], x[0]) for x in conversions]
+    results = [x for x in results
+               if round(x[0]) > 0 and len('%d' % x[0]) < 4]
+    # Choose the first one that is close to the minimum error
+    errors = [abs(x[0] - round(x[0])) for x in results]
+    min_error = min(errors)
+    best_idx = 0
+    while errors[best_idx] - min_error > 0.001:
+        best_idx += 1
+    return '%d%s' % (round(results[best_idx][0]), results[best_idx][1])