def __str__(self):
""" Gets a formatted string of the header of a TRK file.
Returns
-------
info : string
Header information relevant to the TRK format.
"""
vars = self.header.copy()
for attr in dir(Field):
if attr[0] in string.ascii_uppercase:
hdr_field = getattr(Field, attr)
if hdr_field in vars:
vars[attr] = vars[hdr_field]
nb_scalars = self.header[Field.NB_SCALARS_PER_POINT]
scalar_names = [
asstr(s) for s in vars['scalar_name'][:nb_scalars] if len(s) > 0
]
vars['scalar_names'] = '\n '.join(scalar_names)
nb_properties = self.header[Field.NB_PROPERTIES_PER_STREAMLINE]
property_names = [
asstr(s) for s in vars['property_name'][:nb_properties]
if len(s) > 0
]
vars['property_names'] = "\n ".join(property_names)
# Make all byte strings into strings
# Fixes recursion error on Python 3.3
vars = dict((k, asstr(v) if hasattr(v, 'decode') else v)
for k, v in vars.items())
return """\
MAGIC NUMBER: {MAGIC_NUMBER}
v.{version}
dim: {DIMENSIONS}
voxel_sizes: {VOXEL_SIZES}
origin: {ORIGIN}
nb_scalars: {NB_SCALARS_PER_POINT}
scalar_names:\n {scalar_names}
nb_properties: {NB_PROPERTIES_PER_STREAMLINE}
property_names:\n {property_names}
vox_to_world:\n{VOXEL_TO_RASMM}
voxel_order: {VOXEL_ORDER}
image_orientation_patient: {image_orientation_patient}
pad1: {pad1}
pad2: {pad2}
invert_x: {invert_x}
invert_y: {invert_y}
invert_z: {invert_z}
swap_xy: {swap_xy}
swap_yz: {swap_yz}
swap_zx: {swap_zx}
n_count: {NB_STREAMLINES}
hdr_size: {hdr_size}""".format(**vars)
def __str__(self):
""" Gets a formatted string of the header of a TRK file.
Returns
-------
info : string
Header information relevant to the TRK format.
"""
vars = self.header.copy()
for attr in dir(Field):
if attr[0] in string.ascii_uppercase:
hdr_field = getattr(Field, attr)
if hdr_field in vars:
vars[attr] = vars[hdr_field]
nb_scalars = self.header[Field.NB_SCALARS_PER_POINT]
scalar_names = [asstr(s)
for s in vars['scalar_name'][:nb_scalars]
if len(s) > 0]
vars['scalar_names'] = '\n '.join(scalar_names)
nb_properties = self.header[Field.NB_PROPERTIES_PER_STREAMLINE]
property_names = [asstr(s)
for s in vars['property_name'][:nb_properties]
if len(s) > 0]
vars['property_names'] = "\n ".join(property_names)
# Make all byte strings into strings
# Fixes recursion error on Python 3.3
vars = dict((k, asstr(v) if hasattr(v, 'decode') else v)
for k, v in vars.items())
return """\
MAGIC NUMBER: {MAGIC_NUMBER}
v.{version}
dim: {DIMENSIONS}
voxel_sizes: {VOXEL_SIZES}
origin: {ORIGIN}
nb_scalars: {NB_SCALARS_PER_POINT}
scalar_names:\n {scalar_names}
nb_properties: {NB_PROPERTIES_PER_STREAMLINE}
property_names:\n {property_names}
vox_to_world:\n{VOXEL_TO_RASMM}
voxel_order: {VOXEL_ORDER}
image_orientation_patient: {image_orientation_patient}
pad1: {pad1}
pad2: {pad2}
invert_x: {invert_x}
invert_y: {invert_y}
invert_z: {invert_z}
swap_xy: {swap_xy}
swap_yz: {swap_yz}
swap_zx: {swap_zx}
n_count: {NB_STREAMLINES}
hdr_size: {hdr_size}""".format(**vars)
def run_pipes(self, cmd, args=(), cwd=None):
if cwd is None:
cwd = self.working_path
try:
# Start subprocess
cmd_str = self.cmd_str_maker(cmd, args)
proc = Popen(cmd_str, cwd=cwd, stdout=PIPE, stderr=PIPE, shell=NEED_SHELL)
# Execute
stdout, stderr = proc.communicate()
finally:
if proc.poll() is None: # In case we get killed
proc.terminate()
return asstr(stdout), asstr(stderr), proc.returncode
def decode_value_from_name(encoded_name):
""" Decodes a value that has been encoded in the last bytes of a string.
Check :func:`encode_value_in_name` to see how the value has been encoded.
Parameters
----------
encoded_name : bytes
Name in which a value has been encoded or not.
Returns
-------
name : bytes
Name without the encoded value.
value : int
Value decoded from the name.
"""
encoded_name = asstr(encoded_name)
if len(encoded_name) == 0:
return encoded_name, 0
splits = encoded_name.rstrip('\x00').split('\x00')
name = splits[0]
value = 1
if len(splits) == 2:
value = int(splits[1]) # Decode value.
elif len(splits) > 2:
# The remaining bytes are not \x00, raising.
msg = ("Wrong scalar_name or property_name: '{0}'."
" Unused characters should be \\x00.").format(encoded_name)
raise HeaderError(msg)
return name, value
def decode_value_from_name(encoded_name):
""" Decodes a value that has been encoded in the last bytes of a string.
Check :func:`encode_value_in_name` to see how the value has been encoded.
Parameters
----------
encoded_name : bytes
Name in which a value has been encoded or not.
Returns
-------
name : bytes
Name without the encoded value.
value : int
Value decoded from the name.
"""
encoded_name = asstr(encoded_name)
if len(encoded_name) == 0:
return encoded_name, 0
splits = encoded_name.rstrip('\x00').split('\x00')
name = splits[0]
value = 1
if len(splits) == 2:
value = int(splits[1]) # Decode value.
elif len(splits) > 2:
# The remaining bytes are not \x00, raising.
msg = ("Wrong scalar_name or property_name: '{0}'."
" Unused characters should be \\x00.").format(encoded_name)
raise HeaderError(msg)
return name, value
def run_pipes(self, cmd, args=(), cwd=None):
if cwd is None:
cwd = self.working_path
try:
# Start subprocess
cmd_str = self.cmd_str_maker(cmd, args)
proc = Popen(cmd_str,
cwd = cwd,
stdout = PIPE,
stderr = PIPE,
shell = NEED_SHELL)
# Execute
stdout, stderr = proc.communicate()
finally:
if proc.poll() is None: # In case we get killed
proc.terminate()
return asstr(stdout), asstr(stderr), proc.returncode
def _write_header(fileobj, header):
""" Write TCK header to file-like object.
Parameters
----------
fileobj : file-like object
An open file-like object in binary mode pointing to TCK file (and
ready to read from the beginning of the TCK header).
"""
# Fields to exclude
exclude = [
Field.MAGIC_NUMBER, # Handled separately.
Field.NB_STREAMLINES, # Handled separately.
Field.ENDIANNESS, # Handled separately.
Field.VOXEL_TO_RASMM, # Streamlines are always in RAS+ mm.
"count",
"datatype",
"file"
] # Fields being replaced.
lines = []
lines.append(asstr(header[Field.MAGIC_NUMBER]))
lines.append("count: {0:010}".format(header[Field.NB_STREAMLINES]))
lines.append("datatype: Float32LE") # Always Float32LE.
lines.extend([
"{0}: {1}".format(k, v) for k, v in header.items()
if k not in exclude and not k.startswith("_")
])
lines.append("file: . ") # Manually add this last field.
out = "\n".join(lines)
# Check the header is well formatted.
if out.count("\n") > len(lines) - 1: # \n only allowed between lines.
msg = "Key-value pairs cannot contain '\\n':\n{}".format(out)
raise HeaderError(msg)
if out.count(":") > len(lines) - 1:
# : only one per line (except the last one which contains END).
msg = "Key-value pairs cannot contain ':':\n{}".format(out)
raise HeaderError(msg)
# Write header to file.
fileobj.write(asbytes(out))
hdr_len_no_offset = len(out) + 5
# Need to add number of bytes to store offset as decimal string. We
# start with estimate without string, then update if the
# offset-as-decimal-string got longer after adding length of the
# offset string.
new_offset = -1
old_offset = hdr_len_no_offset
while new_offset != old_offset:
old_offset = new_offset
new_offset = hdr_len_no_offset + len(str(old_offset))
fileobj.write(asbytes(str(new_offset) + "\n"))
fileobj.write(asbytes("END\n"))
def __str__(self):
""" Gets a formatted string of the header of a TRK file.
Returns
-------
info : string
Header information relevant to the TRK format.
"""
vars = self.header.copy()
for attr in dir(Field):
if attr[0] in string.ascii_uppercase:
hdr_field = getattr(Field, attr)
if hdr_field in vars:
vars[attr] = vars[hdr_field]
vars['scalar_names'] = '\n '.join([asstr(s)
for s in vars['scalar_name']
if len(s) > 0])
vars['property_names'] = "\n ".join([asstr(s)
for s in vars['property_name']
if len(s) > 0])
return """\
MAGIC NUMBER: {MAGIC_NUMBER}
v.{version}
dim: {DIMENSIONS}
voxel_sizes: {VOXEL_SIZES}
orgin: {ORIGIN}
nb_scalars: {NB_SCALARS_PER_POINT}
scalar_name:\n {scalar_names}
nb_properties: {NB_PROPERTIES_PER_STREAMLINE}
property_name:\n {property_names}
vox_to_world:\n{VOXEL_TO_RASMM}
voxel_order: {VOXEL_ORDER}
image_orientation_patient: {image_orientation_patient}
pad1: {pad1}
pad2: {pad2}
invert_x: {invert_x}
invert_y: {invert_y}
invert_z: {invert_z}
swap_xy: {swap_xy}
swap_yz: {swap_yz}
swap_zx: {swap_zx}
n_count: {NB_STREAMLINES}
hdr_size: {hdr_size}""".format(**vars)
def __str__(self):
""" Gets a formatted string of the header of a TRK file.
Returns
-------
info : string
Header information relevant to the TRK format.
"""
vars = self.header.copy()
for attr in dir(Field):
if attr[0] in string.ascii_uppercase:
hdr_field = getattr(Field, attr)
if hdr_field in vars:
vars[attr] = vars[hdr_field]
vars['scalar_names'] = '\n '.join(
[asstr(s) for s in vars['scalar_name'] if len(s) > 0])
vars['property_names'] = "\n ".join(
[asstr(s) for s in vars['property_name'] if len(s) > 0])
return """\
MAGIC NUMBER: {MAGIC_NUMBER}
v.{version}
dim: {DIMENSIONS}
voxel_sizes: {VOXEL_SIZES}
orgin: {ORIGIN}
nb_scalars: {NB_SCALARS_PER_POINT}
scalar_name:\n {scalar_names}
nb_properties: {NB_PROPERTIES_PER_STREAMLINE}
property_name:\n {property_names}
vox_to_world:\n{VOXEL_TO_RASMM}
voxel_order: {VOXEL_ORDER}
image_orientation_patient: {image_orientation_patient}
pad1: {pad1}
pad2: {pad2}
invert_x: {invert_x}
invert_y: {invert_y}
invert_z: {invert_z}
swap_xy: {swap_xy}
swap_yz: {swap_yz}
swap_zx: {swap_zx}
n_count: {NB_STREAMLINES}
hdr_size: {hdr_size}""".format(**vars)
def get_affine_trackvis_to_rasmm(header):
""" Get affine mapping trackvis voxelmm space to RAS+ mm space
The streamlines in a trackvis file are in 'voxelmm' space, where the
coordinates refer to the corner of the voxel.
Compute the affine matrix that will bring them back to RAS+ mm space, where
the coordinates refer to the center of the voxel.
Parameters
----------
header : dict
Dict containing trackvis header.
Returns
-------
aff_tv2ras : shape (4, 4) array
Affine array mapping coordinates in 'voxelmm' space to RAS+ mm space.
"""
# TRK's streamlines are in 'voxelmm' space, we will compute the
# affine matrix that will bring them back to RAS+ and mm space.
affine = np.eye(4)
# The affine matrix found in the TRK header requires the points to
# be in the voxel space.
# voxelmm -> voxel
scale = np.eye(4)
scale[range(3), range(3)] /= header[Field.VOXEL_SIZES]
affine = np.dot(scale, affine)
# TrackVis considers coordinate (0,0,0) to be the corner of the
# voxel whereas streamlines returned assumes (0,0,0) to be the
# center of the voxel. Thus, streamlines are shifted by half a voxel.
offset = np.eye(4)
offset[:-1, -1] -= 0.5
affine = np.dot(offset, affine)
# If the voxel order implied by the affine does not match the voxel
# order in the TRK header, change the orientation.
# voxel (header) -> voxel (affine)
header_ornt = asstr(header[Field.VOXEL_ORDER])
affine_ornt = "".join(aff2axcodes(header[Field.VOXEL_TO_RASMM]))
header_ornt = axcodes2ornt(header_ornt)
affine_ornt = axcodes2ornt(affine_ornt)
ornt = nib.orientations.ornt_transform(header_ornt, affine_ornt)
M = nib.orientations.inv_ornt_aff(ornt, header[Field.DIMENSIONS])
affine = np.dot(M, affine)
# Applied the affine found in the TRK header.
# voxel -> rasmm
voxel_to_rasmm = header[Field.VOXEL_TO_RASMM]
affine_voxmm_to_rasmm = np.dot(voxel_to_rasmm, affine)
return affine_voxmm_to_rasmm.astype(np.float32)
def get_affine_trackvis_to_rasmm(header):
""" Get affine mapping trackvis voxelmm space to RAS+ mm space
The streamlines in a trackvis file are in 'voxelmm' space, where the
coordinates refer to the corner of the voxel.
Compute the affine matrix that will bring them back to RAS+ mm space, where
the coordinates refer to the center of the voxel.
Parameters
----------
header : dict
Dict containing trackvis header.
Returns
-------
aff_tv2ras : shape (4, 4) array
Affine array mapping coordinates in 'voxelmm' space to RAS+ mm space.
"""
# TRK's streamlines are in 'voxelmm' space, we will compute the
# affine matrix that will bring them back to RAS+ and mm space.
affine = np.eye(4)
# The affine matrix found in the TRK header requires the points to
# be in the voxel space.
# voxelmm -> voxel
scale = np.eye(4)
scale[range(3), range(3)] /= header[Field.VOXEL_SIZES]
affine = np.dot(scale, affine)
# TrackVis considers coordinate (0,0,0) to be the corner of the
# voxel whereas streamlines returned assumes (0,0,0) to be the
# center of the voxel. Thus, streamlines are shifted by half a voxel.
offset = np.eye(4)
offset[:-1, -1] -= 0.5
affine = np.dot(offset, affine)
# If the voxel order implied by the affine does not match the voxel
# order in the TRK header, change the orientation.
# voxel (header) -> voxel (affine)
header_ornt = asstr(header[Field.VOXEL_ORDER])
affine_ornt = "".join(aff2axcodes(header[Field.VOXEL_TO_RASMM]))
header_ornt = axcodes2ornt(header_ornt)
affine_ornt = axcodes2ornt(affine_ornt)
ornt = nib.orientations.ornt_transform(header_ornt, affine_ornt)
M = nib.orientations.inv_ornt_aff(ornt, header[Field.DIMENSIONS])
affine = np.dot(M, affine)
# Applied the affine found in the TRK header.
# voxel -> rasmm
voxel_to_rasmm = header[Field.VOXEL_TO_RASMM]
affine_voxmm_to_rasmm = np.dot(voxel_to_rasmm, affine)
return affine_voxmm_to_rasmm.astype(np.float32)
def _write_header(fileobj, header):
""" Write TCK header to file-like object.
Parameters
----------
fileobj : file-like object
An open file-like object in binary mode pointing to TCK file (and
ready to read from the beginning of the TCK header).
"""
# Fields to exclude
exclude = [Field.MAGIC_NUMBER, # Handled separately.
Field.NB_STREAMLINES, # Handled separately.
Field.ENDIANNESS, # Handled separately.
Field.VOXEL_TO_RASMM, # Streamlines are always in RAS+ mm.
"count", "datatype", "file"] # Fields being replaced.
lines = []
lines.append(asstr(header[Field.MAGIC_NUMBER]))
lines.append("count: {0:010}".format(header[Field.NB_STREAMLINES]))
lines.append("datatype: Float32LE") # Always Float32LE.
lines.extend(["{0}: {1}".format(k, v)
for k, v in header.items()
if k not in exclude and not k.startswith("_")])
lines.append("file: . ") # Manually add this last field.
out = "\n".join(lines)
# Check the header is well formatted.
if out.count("\n") > len(lines) - 1: # \n only allowed between lines.
msg = "Key-value pairs cannot contain '\\n':\n{}".format(out)
raise HeaderError(msg)
if out.count(":") > len(lines) - 1:
# : only one per line (except the last one which contains END).
msg = "Key-value pairs cannot contain ':':\n{}".format(out)
raise HeaderError(msg)
# Write header to file.
fileobj.write(asbytes(out))
hdr_len_no_offset = len(out) + 5
# Need to add number of bytes to store offset as decimal string. We
# start with estimate without string, then update if the
# offset-as-decimal-string got longer after adding length of the
# offset string.
new_offset = -1
old_offset = hdr_len_no_offset
while new_offset != old_offset:
old_offset = new_offset
new_offset = hdr_len_no_offset + len(str(old_offset))
fileobj.write(asbytes(str(new_offset) + "\n"))
fileobj.write(asbytes("END\n"))
def is_correct_format(cls, fileobj):
""" Check if the file is in TCK format.
Parameters
----------
fileobj : string or file-like object
If string, a filename; otherwise an open file-like object in
binary mode pointing to TCK file (and ready to read from the
beginning of the TCK header). Note that calling this function
does not change the file position.
Returns
-------
is_correct_format : {True, False}
Returns True if `fileobj` is compatible with TCK format,
otherwise returns False.
"""
with Opener(fileobj) as f:
magic_number = asstr(f.fobj.readline())
f.seek(-len(magic_number), os.SEEK_CUR)
return magic_number.strip() == cls.MAGIC_NUMBER
def is_correct_format(cls, fileobj):
""" Check if the file is in TCK format.
Parameters
----------
fileobj : string or file-like object
If string, a filename; otherwise an open file-like object in
binary mode pointing to TCK file (and ready to read from the
beginning of the TCK header). Note that calling this function
does not change the file position.
Returns
-------
is_correct_format : {True, False}
Returns True if `fileobj` is compatible with TCK format,
otherwise returns False.
"""
with Opener(fileobj) as f:
magic_number = asstr(f.fobj.readline())
f.seek(-len(magic_number), os.SEEK_CUR)
return magic_number.strip() == cls.MAGIC_NUMBER
def aff_from_hdr(trk_hdr, atleast_v2=None):
''' Return voxel to mm affine from trackvis header
Affine is mapping from voxel space to Nifti (RAS) output coordinate
system convention; x: Left -> Right, y: Posterior -> Anterior, z:
Inferior -> Superior.
Parameters
----------
trk_hdr : mapping
Mapping with trackvis header keys ``version``. If ``version == 2``, we
also expect ``vox_to_ras``.
atleast_v2 : None or bool
If None, currently defaults to False. This will change to True in
future versions. If True, require that there is a valid 'vox_to_ras'
affine, raise HeaderError otherwise. If False, look for valid
'vox_to_ras' affine, but fall back to best guess from version 1 fields
otherwise.
Returns
-------
aff : (4,4) array
affine giving mapping from voxel coordinates (affine applied on
the left to points on the right) to millimeter coordinates in the
RAS coordinate system
Notes
-----
Our initial idea was to try and work round the deficiencies of the version 1
format by using the DICOM orientation fields to store the affine. This
proved difficult in practice because trackvis (the application) doesn't
allow negative voxel sizes (needed for recording axis flips) and sets the
origin field to 0. In future, we'll raise an error rather than try and
estimate the affine from version 1 fields
'''
if atleast_v2 is None:
warnings.warn('Defaulting to `atleast_v2` of False. Future versions '
'will default to True',
FutureWarning,
stacklevel=2)
atleast_v2 = False
if trk_hdr['version'] == 2:
aff = trk_hdr['vox_to_ras']
if aff[3,3] != 0:
return aff
if atleast_v2:
raise HeaderError('Requiring version 2 affine and this affine is '
'not valid')
# Now we are in the dark world of the DICOM fields. We might have made this
# one ourselves, in which case the origin might be set, and it might have
# negative voxel sizes
aff = np.eye(4)
# The IOP field has only two of the three columns we need
iop = trk_hdr['image_orientation_patient'].reshape(2,3).T
# R might be a rotation matrix (and so completed by the cross product of the
# first two columns), or it might be an orthogonal matrix with negative
# determinant. We try pure rotation first
R = np.c_[iop, np.cross(*iop.T)]
vox = trk_hdr['voxel_size']
aff[:3,:3] = R * vox
aff[:3,3] = trk_hdr['origin']
aff = np.dot(DPCS_TO_TAL, aff)
# Next we check against the 'voxel_order' field if present and not empty.
try:
voxel_order = asstr(np.asscalar(trk_hdr['voxel_order']))
except KeyError, ValueError:
voxel_order = ''
def _check_hdr_points_space(hdr, points_space):
""" Check header `hdr` for consistency with transform `points_space`
Parameters
----------
hdr : ndarray
trackvis header as structured ndarray
points_space : {None, 'voxmm', 'voxel', 'rasmm'
nature of transform that we will (elsewhere) apply to streamlines paired
with `hdr`. None or 'voxmm' means pass through with no futher checks.
'voxel' checks for all ``hdr['voxel_sizes'] being <= zero (error) or any
being zero (warning). 'rasmm' checks for presence of non-zeros affine
in ``hdr['vox_to_ras']``, and that the affine therein corresponds to
``hdr['voxel_order']`` and ''hdr['voxe_sizes']`` - and raises an error
otherwise.
Returns
-------
None
Notes
-----
"""
if points_space is None or points_space == 'voxmm':
return
if points_space == 'voxel':
voxel_size = hdr['voxel_size']
if np.any(voxel_size < 0):
raise HeaderError('Negative voxel sizes %s not valid for voxel - '
'voxmm conversion' % voxel_size)
if np.all(voxel_size == 0):
raise HeaderError('Cannot convert between voxels and voxmm when '
'"voxel_sizes" all 0')
if np.any(voxel_size == 0):
warnings.warn('zero values in "voxel_size" - %s' % voxel_size)
return
elif points_space == 'rasmm':
try:
affine = hdr['vox_to_ras']
except ValueError:
raise HeaderError('Need "vox_to_ras" field to get '
'affine with which to convert points; '
'this is present for headers >= version 2')
if np.all(affine == 0) or affine[3,3] == 0:
raise HeaderError('Need non-zero affine to convert between '
'rasmm points and voxmm')
zooms = hdr['voxel_size']
aff_zooms = np.sqrt(np.sum(affine[:3,:3]**2,axis=0))
if not np.allclose(aff_zooms, zooms):
raise HeaderError('Affine zooms %s differ from voxel_size '
'field value %s' % (aff_zooms, zooms))
aff_order = ''.join(aff2axcodes(affine))
voxel_order = asstr(np.asscalar(hdr['voxel_order']))
if voxel_order == '':
voxel_order = 'LPS' # trackvis default
if not voxel_order == aff_order:
raise HeaderError('Affine implies voxel_order %s but '
'header voxel_order is %s' %
(aff_order, voxel_order))
else:
raise ValueError('Painfully confusing "points_space" value of "%s"'
% points_space)
def _read_header(fileobj):
""" Reads a TCK header from a file.
Parameters
----------
fileobj : string or file-like object
If string, a filename; otherwise an open file-like object in
binary mode pointing to TCK file (and ready to read from the
beginning of the TCK header). Note that calling this function
does not change the file position.
Returns
-------
header : dict
Metadata associated with this tractogram file.
"""
# Record start position if this is a file-like object
start_position = fileobj.tell() if hasattr(fileobj, 'tell') else None
with Opener(fileobj) as f:
# Read magic number
magic_number = f.fobj.readline().strip()
# Read all key-value pairs contained in the header.
buf = asstr(f.fobj.readline())
while not buf.rstrip().endswith("END"):
buf += asstr(f.fobj.readline())
offset_data = f.tell()
# Build header dictionary from the buffer.
hdr = dict(item.split(': ') for item in buf.rstrip().split('\n')[:-1])
hdr[Field.MAGIC_NUMBER] = magic_number
# Check integrity of TCK header.
if 'datatype' not in hdr:
msg = ("Missing 'datatype' attribute in TCK header."
" Assuming it is Float32LE.")
warnings.warn(msg, HeaderWarning)
hdr['datatype'] = "Float32LE"
if not hdr['datatype'].startswith('Float32'):
msg = ("TCK only supports float32 dtype but 'datatype: {}' was"
" specified in the header.").format(hdr['datatype'])
raise HeaderError(msg)
if 'file' not in hdr:
msg = ("Missing 'file' attribute in TCK header."
" Will try to guess it.")
warnings.warn(msg, HeaderWarning)
hdr['file'] = '. {}'.format(offset_data)
if hdr['file'].split()[0] != '.':
msg = ("TCK only supports single-file - in other words the"
" filename part must be specified as '.' but '{}' was"
" specified.").format(hdr['file'].split()[0])
raise HeaderError("Missing 'file' attribute in TCK header.")
# Set endianness and _dtype attributes in the header.
hdr[Field.ENDIANNESS] = '>' if hdr['datatype'].endswith('BE') else '<'
hdr['_dtype'] = np.dtype(hdr[Field.ENDIANNESS] + 'f4')
# Keep the file position where the data begin.
hdr['_offset_data'] = int(hdr['file'].split()[1])
# Set the file position where it was, if it was previously open.
if start_position is not None:
fileobj.seek(start_position, os.SEEK_SET)
return hdr
def test_to_str():
# Test routine to convert to string
assert_equal("1", to_str(1))
assert_equal("1.0", to_str(1.0))
assert_equal("from", to_str(asstr("from")))
assert_equal("from", to_str(asbytes("from")))
def test_to_str():
# Test routine to convert to string
assert_equal('1', to_str(1))
assert_equal('1.0', to_str(1.0))
assert_equal('from', to_str(asstr('from')))
assert_equal('from', to_str(asbytes('from')))
def _check_hdr_points_space(hdr, points_space):
""" Check header `hdr` for consistency with transform `points_space`
Parameters
----------
hdr : ndarray
trackvis header as structured ndarray
points_space : {None, 'voxmm', 'voxel', 'rasmm'
nature of transform that we will (elsewhere) apply to streamlines paired
with `hdr`. None or 'voxmm' means pass through with no futher checks.
'voxel' checks for all ``hdr['voxel_sizes'] being <= zero (error) or any
being zero (warning). 'rasmm' checks for presence of non-zeros affine
in ``hdr['vox_to_ras']``, and that the affine therein corresponds to
``hdr['voxel_order']`` and ''hdr['voxe_sizes']`` - and raises an error
otherwise.
Returns
-------
None
Notes
-----
"""
if points_space is None or points_space == 'voxmm':
return
if points_space == 'voxel':
voxel_size = hdr['voxel_size']
if np.any(voxel_size < 0):
raise HeaderError('Negative voxel sizes %s not valid for voxel - '
'voxmm conversion' % voxel_size)
if np.all(voxel_size == 0):
raise HeaderError('Cannot convert between voxels and voxmm when '
'"voxel_sizes" all 0')
if np.any(voxel_size == 0):
warnings.warn('zero values in "voxel_size" - %s' % voxel_size)
return
elif points_space == 'rasmm':
try:
affine = hdr['vox_to_ras']
except ValueError:
raise HeaderError('Need "vox_to_ras" field to get '
'affine with which to convert points; '
'this is present for headers >= version 2')
if np.all(affine == 0) or affine[3, 3] == 0:
raise HeaderError('Need non-zero affine to convert between '
'rasmm points and voxmm')
zooms = hdr['voxel_size']
aff_zooms = np.sqrt(np.sum(affine[:3, :3]**2, axis=0))
if not np.allclose(aff_zooms, zooms):
raise HeaderError('Affine zooms %s differ from voxel_size '
'field value %s' % (aff_zooms, zooms))
aff_order = ''.join(aff2axcodes(affine))
voxel_order = asstr(np.asscalar(hdr['voxel_order']))
if voxel_order == '':
voxel_order = 'LPS' # trackvis default
if not voxel_order == aff_order:
raise HeaderError('Affine implies voxel_order %s but '
'header voxel_order is %s' %
(aff_order, voxel_order))
else:
raise ValueError('Painfully confusing "points_space" value of "%s"' %
points_space)
def _read_header(fileobj):
""" Reads a TCK header from a file.
Parameters
----------
fileobj : string or file-like object
If string, a filename; otherwise an open file-like object in
binary mode pointing to TCK file (and ready to read from the
beginning of the TCK header). Note that calling this function
does not change the file position.
Returns
-------
header : dict
Metadata associated with this tractogram file.
"""
# Record start position if this is a file-like object
start_position = fileobj.tell() if hasattr(fileobj, 'tell') else None
with Opener(fileobj) as f:
# Read magic number
magic_number = f.fobj.readline().strip()
# Read all key-value pairs contained in the header.
buf = asstr(f.fobj.readline())
while not buf.rstrip().endswith("END"):
buf += asstr(f.fobj.readline())
offset_data = f.tell()
# Build header dictionary from the buffer.
hdr = dict(item.split(': ') for item in buf.rstrip().split('\n')[:-1])
hdr[Field.MAGIC_NUMBER] = magic_number
# Check integrity of TCK header.
if 'datatype' not in hdr:
msg = ("Missing 'datatype' attribute in TCK header."
" Assuming it is Float32LE.")
warnings.warn(msg, HeaderWarning)
hdr['datatype'] = "Float32LE"
if not hdr['datatype'].startswith('Float32'):
msg = ("TCK only supports float32 dtype but 'datatype: {}' was"
" specified in the header.").format(hdr['datatype'])
raise HeaderError(msg)
if 'file' not in hdr:
msg = ("Missing 'file' attribute in TCK header."
" Will try to guess it.")
warnings.warn(msg, HeaderWarning)
hdr['file'] = '. {}'.format(offset_data)
if hdr['file'].split()[0] != '.':
msg = ("TCK only supports single-file - in other words the"
" filename part must be specified as '.' but '{}' was"
" specified.").format(hdr['file'].split()[0])
raise HeaderError("Missing 'file' attribute in TCK header.")
# Set endianness and _dtype attributes in the header.
hdr[Field.ENDIANNESS] = '>' if hdr['datatype'].endswith('BE') else '<'
hdr['_dtype'] = np.dtype(hdr[Field.ENDIANNESS] + 'f4')
# Keep the file position where the data begin.
hdr['_offset_data'] = int(hdr['file'].split()[1])
# Set the file position where it was, if it was previously open.
if start_position is not None:
fileobj.seek(start_position, os.SEEK_SET)
return hdr
def test_to_str():
# Test routine to convert to string
assert_equal('1', to_str(1))
assert_equal('1.0', to_str(1.0))
assert_equal('from', to_str(asstr('from')))
assert_equal('from', to_str(asbytes('from')))
def aff_from_hdr(trk_hdr, atleast_v2=None):
''' Return voxel to mm affine from trackvis header
Affine is mapping from voxel space to Nifti (RAS) output coordinate
system convention; x: Left -> Right, y: Posterior -> Anterior, z:
Inferior -> Superior.
Parameters
----------
trk_hdr : mapping
Mapping with trackvis header keys ``version``. If ``version == 2``, we
also expect ``vox_to_ras``.
atleast_v2 : None or bool
If None, currently defaults to False. This will change to True in
future versions. If True, require that there is a valid 'vox_to_ras'
affine, raise HeaderError otherwise. If False, look for valid
'vox_to_ras' affine, but fall back to best guess from version 1 fields
otherwise.
Returns
-------
aff : (4,4) array
affine giving mapping from voxel coordinates (affine applied on
the left to points on the right) to millimeter coordinates in the
RAS coordinate system
Notes
-----
Our initial idea was to try and work round the deficiencies of the version 1
format by using the DICOM orientation fields to store the affine. This
proved difficult in practice because trackvis (the application) doesn't
allow negative voxel sizes (needed for recording axis flips) and sets the
origin field to 0. In future, we'll raise an error rather than try and
estimate the affine from version 1 fields
'''
if atleast_v2 is None:
warnings.warn(
'Defaulting to `atleast_v2` of False. Future versions '
'will default to True',
FutureWarning,
stacklevel=2)
atleast_v2 = False
if trk_hdr['version'] == 2:
aff = trk_hdr['vox_to_ras']
if aff[3, 3] != 0:
return aff
if atleast_v2:
raise HeaderError('Requiring version 2 affine and this affine is '
'not valid')
# Now we are in the dark world of the DICOM fields. We might have made this
# one ourselves, in which case the origin might be set, and it might have
# negative voxel sizes
aff = np.eye(4)
# The IOP field has only two of the three columns we need
iop = trk_hdr['image_orientation_patient'].reshape(2, 3).T
# R might be a rotation matrix (and so completed by the cross product of the
# first two columns), or it might be an orthogonal matrix with negative
# determinant. We try pure rotation first
R = np.c_[iop, np.cross(*iop.T)]
vox = trk_hdr['voxel_size']
aff[:3, :3] = R * vox
aff[:3, 3] = trk_hdr['origin']
aff = np.dot(DPCS_TO_TAL, aff)
# Next we check against the 'voxel_order' field if present and not empty.
try:
voxel_order = asstr(np.asscalar(trk_hdr['voxel_order']))
except KeyError, ValueError:
voxel_order = ''
