larmor.io.formats#

Reading and writing each file format; larmor.io loads them by path.

`read_freesurfer_label`	Reads the vertex indices of a FreeSurfer label file, such as `lh.cortex.label`.
`read_freesurfer_surface`	Reads a FreeSurfer triangle surface, such as `lh.white` or `lh.pial`.
`read_freesurfer_values`	Reads a FreeSurfer per-vertex file ("new curv" format), such as `lh.curv`.
`read_gifti_surface`	Reads a GIfTI surface (.surf.gii) and any values per vertex stored with it.
`read_gifti_values`	Reads the values per vertex of a GIfTI file (.shape.gii, .func.gii, .label.gii).
`read_mif`	Reads a MIF file (`mif`, `mif.gz` or `mih`) into a `Volume`.
`read_mif_gradients`	Reads the gradient table (`dw_scheme`) of a MIF file, from its header only.
`read_mif_header`	Reads only the header of a MIF file, without the data.
`read_nifti`	Reads a NIfTI-1 or NIfTI-2 file, plain or gzip, into a `Volume`.
`read_nifti_header`	Reads only the header of a NIfTI file, without the data.
`read_tck`	Reads a TCK file (MRtrix tractogram) into a `Tractogram`.
`read_trk`	Reads a TRK file (TrackVis tractogram) into a `Tractogram`.
`read_vtk`	Reads a legacy VTK polydata file of lines (`vtk`, `fib`) into a `Tractogram`.
`write_freesurfer_surface`	Writes a surface as a FreeSurfer triangle file.
`write_freesurfer_values`	Writes values per vertex as a FreeSurfer "new curv" file.
`write_gifti_surface`	Writes a surface and its values per vertex to a GIfTI file (.surf.gii).
`write_gifti_values`	Writes named values per vertex to a GIfTI file (.shape.gii or .func.gii).
`write_mif`	Writes a `Volume`, and optionally its gradient table, as MIF.
`write_nifti`	Writes a `Volume` as a NIfTI file, compressed if the name ends in ".gz".
`write_tck`	Writes a `Tractogram` as a TCK file, as little-endian float32.
`write_trk`	Writes a `Tractogram` as a TRK file (version 2, little-endian).
`write_vtk`	Writes a `Tractogram` as a legacy VTK polydata file (`vtk` or `fib`).

larmor.io.formats.read_freesurfer_label(path)#

Reads the vertex indices of a FreeSurfer label file, such as lh.cortex.label.

The file is text: a comment line, the vertex count, then one line per vertex with its index, its tkregister coordinates and a value. Only the indices are returned; turn them into a mask for a surface with mask = np.zeros(surface.num_vertices, dtype=bool); mask[indices] = True.

Parameters:: path (str | Path) – The label file.
Returns:: np.ndarray – (N,) int64 vertex indices, in the file’s order.
Raises:: ValueError – If the count is not a number or is negative, or the file has fewer vertex lines than its count or a malformed one. The message starts with the path.
Return type:: ndarray

larmor.io.formats.read_freesurfer_surface(path)#

Reads a FreeSurfer triangle surface, such as lh.white or lh.pial.

FreeSurfer stores vertices in tkregister space. With a valid volume info footer they are converted to scanner RAS and the footer’s volume becomes the reference; without one they are kept as stored and the reference is None.

Parameters:: path (str | Path) – Path to the file.
Returns:: Surface – The mesh, with no values per vertex.
Raises:: ValueError – If the file is not a FreeSurfer triangle file or is truncated.
Return type:: Surface

larmor.io.formats.read_freesurfer_values(path)#

Reads a FreeSurfer per-vertex file (“new curv” format), such as lh.curv.

Parameters:: path (str | Path) – The per-vertex file, such as lh.curv.
Returns:: np.ndarray – (V,) float32, one value per vertex.
Raises:: ValueError – If the file is not in the new curv format, holds more than one value per vertex, or is truncated.
Return type:: ndarray

larmor.io.formats.read_gifti_surface(path)#

Reads a GIfTI surface (.surf.gii) and any values per vertex stored with it.

Files written by FreeSurfer (mris_convert) store tkregister RAS and describe the volume in the pointset’s VolGeom metadata: those vertices are converted to scanner RAS and the volume becomes the reference, as for a FreeSurfer surface, unless the pointset’s DataSpace already says scanner space. Other vertices are taken as stored (Workbench, fMRIPrep and nibabel write scanner RAS); the file’s coordinate transform is not applied.

Parameters:

path (str | Path) – Path to the file.

Returns:

Surface –

The mesh, with the file’s other arrays in vertex_data, named: after their “Name” metadata (or “data<index>”). The reference is the VolGeom volume, or None without one.

Raises:

ValueError – If the file is not GIfTI XML, does not hold exactly one pointset and one triangle array, an array cannot be decoded, or its VolGeom metadata is malformed. The message starts with the path.

Return type:

Surface

larmor.io.formats.read_gifti_values(path, *, unnamed=None)#

Reads the values per vertex of a GIfTI file (.shape.gii, .func.gii, .label.gii).

Parameters:

path (str | Path) – Path to the file.
unnamed (str | None) – The name of an array without “Name” metadata; with several such arrays, the array’s index is added. Defaults to None (“data<index>”).

Returns:

dict[str, np.ndarray] –

Each array that is not a mesh, named after its: ”Name” metadata (or as unnamed says). Label files give the integer keys; their label table is not read.

Raises:

ValueError – If the file is not GIfTI XML or an array cannot be decoded. The message starts with the path.

Return type:

dict[str, ndarray]

larmor.io.formats.read_mif(path, *, on_progress=None)#

Reads a MIF file (mif, mif.gz or mih) into a Volume.

The axes are those of the header’s dim, whatever the layout on disk. The data keeps its on-disk type, in native byte order (Bit becomes bool); scaling is stored on the Volume, not applied.

Parameters:

path (str | Path) – The MIF file.
on_progress (Callable[[int, int], None] | None) – Called as the file is read, see load_volume.

Returns:

Volume – The volume.

Raises:

ValueError – If the file is not a MIF file Larmor can read, or is too short.
ReadCancelledError – If on_progress raises it.

Return type:

Volume

larmor.io.formats.read_mif_gradients(path)#

Reads the gradient table (dw_scheme) of a MIF file, from its header only.

The directions are already in world coordinates, so nothing is converted.

Parameters:: path (str | Path) – The MIF file.
Returns:: GradientTable – The table.
Raises:: ValueError – If the header has no dw_scheme, a line is not 4 numbers, or the number of lines differs from the fourth dimension.
Return type:: GradientTable

larmor.io.formats.read_mif_header(path)#

Reads only the header of a MIF file, without the data.

Parameters:: path (str | Path) – The mif, mif.gz or mih file.
Returns:: The grid, and the full shape of the data – (X, Y, Z) or (X, Y, Z, N).
Raises:: ValueError – If the file is not a MIF file Larmor can read.
Return type:: tuple[Grid, tuple[int, …]]

larmor.io.formats.read_nifti(path, *, on_progress=None)#

Reads a NIfTI-1 or NIfTI-2 file, plain or gzip, into a Volume.

The data keeps its on-disk type, in native byte order; scl_slope and scl_inter are stored on the Volume, not applied.

Parameters:

path (str | Path) – The nii or nii.gz file.
on_progress (Callable[[int, int], None] | None) – Called as the file is read, see load_volume.

Returns:

Volume – The image, with its scaling not applied.

Raises:

ValueError – If the file is not a NIfTI file Larmor can read, or is too short.
ReadCancelledError – If on_progress raises it.

Return type:

Volume

larmor.io.formats.read_nifti_header(path)#

Reads only the header of a NIfTI file, without the data.

Parameters:: path (str | Path) – The nii or nii.gz file.
Returns:: The grid, and the full shape of the data – (X, Y, Z) or (X, Y, Z, N).
Raises:: ValueError – If the file is not a NIfTI file Larmor can read.
Return type:: tuple[Grid, tuple[int, …]]

larmor.io.formats.read_tck(path, *, on_progress=None)#

Reads a TCK file (MRtrix tractogram) into a Tractogram.

The data is read to the end, whatever the header’s count says: an incomplete last point or last streamline (an interrupted tckgen) is dropped with a warning, and a count that disagrees with the data, as in a file whose writing was interrupted, gives a warning. The points are float32; the tractogram has no reference grid.

Parameters:

path (str | Path) – The tck file.
on_progress (Callable[[int, int], None] | None) – Called as the file is read, see load_volume.

Returns:

The streamlines of the file.

Raises:

ValueError – If the file is not a TCK file Larmor can read.
ReadCancelledError – If on_progress raises it.

Return type:

Tractogram

larmor.io.formats.read_trk(path, *, reference=None, on_progress=None)#

Reads a TRK file (TrackVis tractogram) into a Tractogram.

Points are converted from TrackVis voxel mm to world coordinates as nibabel does. Scalars go into point_data and properties into streamline_data, named as in the header. The data is read to the end, whatever n_count says; an incomplete last streamline is dropped with a warning. A file that TrkWriter did not finish (an interrupted run), or whose n_count is not 0 and disagrees with the data, gives a warning that it may be incomplete.

Parameters:

path (str | Path) – The trk file.
reference (Grid | None) – The grid of the image the tractogram belongs to. Needed when the file has no vox_to_ras (version 1); otherwise it must match the file’s.
on_progress (Callable[[int, int], None] | None) – Called as the file is read, see load_volume.

Returns:

Tractogram – The streamlines, in world coordinates, with the file’s scalars and properties.

Raises:

ValueError – If the file is not a TRK file Larmor can read, has no vox_to_ras and no reference is given, or the reference does not match the file.
ReadCancelledError – If on_progress raises it.

Return type:

Tractogram

larmor.io.formats.read_vtk(path, *, on_progress=None)#

Reads a legacy VTK polydata file of lines (vtk, fib) into a Tractogram.

ASCII and binary files are read, with legacy or version 5.1 LINES. The points are taken as stored (world coordinates) and gathered in line order; points no line uses are dropped. POINT_DATA and CELL_DATA arrays go into point_data and streamline_data.

Parameters:

path (str | Path) – The vtk or fib file.
on_progress (Callable[[int, int], None] | None) – Called as the file is read, see load_volume.

Returns:

Tractogram – The streamlines, in world coordinates.

Raises:

ValueError – If the file is not a legacy VTK polydata of lines Larmor can read.
ReadCancelledError – If on_progress raises it.

Return type:

Tractogram

larmor.io.formats.write_freesurfer_surface(surface, path)#

Writes a surface as a FreeSurfer triangle file.

With a reference, the vertices are converted back to tkregister space and the reference is written as the volume info footer. Values per vertex are not written; use write_freesurfer_values.

Parameters:

surface (Surface) – The surface to write.
path (str | Path) – The file to write.

larmor.io.formats.write_freesurfer_values(values, path, *, num_faces=0)#

Writes values per vertex as a FreeSurfer “new curv” file.

Parameters:

values (ndarray) – (V,) values, written as float32.
path (str | Path) – Path to the file.
num_faces (int) – The face count of the mesh, stored in the header. Defaults to 0, as nibabel writes.

Raises:

ValueError – If values is not one-dimensional.

larmor.io.formats.write_gifti_surface(surface, path)#

Writes a surface and its values per vertex to a GIfTI file (.surf.gii).

Vertices are written as float32 in scanner space, faces as int32, and each vertex_data array as its own data array named by its key. The reference is not written: GIfTI has no place for it.

Parameters:

surface (Surface) – The surface to write.
path (str | Path) – Path to the file.

Raises:

ValueError – If a vertex_data array holds integers beyond int32.

larmor.io.formats.write_gifti_values(values, path)#

Writes named values per vertex to a GIfTI file (.shape.gii or .func.gii).

Parameters:

values (dict[str, ndarray]) – Arrays whose first axis is the vertices.
path (str | Path) – Path to the file.

Raises:

ValueError – If an array is a scalar or holds integers beyond int32.

larmor.io.formats.write_mif(volume, path, *, gradients=None)#

Writes a Volume, and optionally its gradient table, as MIF.

A mif holds header and data, compressed if the name ends in “.gz”; a mih holds the header, with the data in a dat of the same name. The data is written in its own type, little-endian, x fastest (layout: +0,+1,+2); bool as Bit. No other metadata is written.

Parameters:

volume (Volume) – The volume to write.
path (str | Path) – The mif, mif.gz or mih file; existing files are overwritten.
gradients (GradientTable | None) – Written into the header as dw_scheme, in world coordinates. Defaults to None.

Raises:

ValueError – If MIF cannot store the data’s type (complex, float16), or gradients does not have one entry per volume.

larmor.io.formats.write_nifti(volume, path)#

Writes a Volume as a NIfTI file, compressed if the name ends in “.gz”.

The file is NIfTI-1, or NIfTI-2 when a dimension is larger than NIfTI-1 can hold (32767), as MRtrix does; little-endian, in the data’s own type, with the volume’s slope and intercept. Boolean data (masks) is written as uint8. No other metadata is written.

Parameters:

volume (Volume) – The volume to write.
path (str | Path) – The nii or nii.gz file; an existing file is overwritten.

Raises:

ValueError – If NIfTI cannot store the data’s type (for example float16).

larmor.io.formats.write_tck(tractogram, path, *, timestamp=None)#

Writes a Tractogram as a TCK file, as little-endian float32.

Only the points are written: TCK holds no point_data, streamline_data or reference grid.

Parameters:

tractogram (Tractogram) – The tractogram to write.
path (str | Path) – The tck file; an existing file is overwritten.
timestamp (str | None) – Written as the header’s timestamp, which MRtrix uses to pair the file with its TSF files: pass the same value to write_tsf. Defaults to None, no timestamp.

Raises:

ValueError – If a point is NaN or infinite, which TCK reads as the end of a streamline or of the file, or timestamp has a ‘#’ or a line break.

larmor.io.formats.write_trk(tractogram, path, *, reference=None)#

Writes a Tractogram as a TRK file (version 2, little-endian).

The header comes from the reference grid: dim, voxel_size, vox_to_ras and voxel_order (the orientation of its affine). point_data is written as scalars and streamline_data as properties, named as nibabel names them.

Parameters:

tractogram (Tractogram) – The tractogram to write.
path (str | Path) – The trk file; an existing file is overwritten.
reference (Grid | None) – The grid of the image the tractogram belongs to. Defaults to the tractogram’s own reference.

Raises:

ValueError – If there is no reference grid, its shape does not fit TRK, or there are too many or too long names.

larmor.io.formats.write_vtk(tractogram, path, *, binary=True)#

Writes a Tractogram as a legacy VTK polydata file (vtk or fib).

Version 3.0, big-endian float32 points and int32 lines. point_data and streamline_data are written as FIELD arrays under POINT_DATA and CELL_DATA, each in its own type (bool as unsigned_char).

Parameters:

tractogram (Tractogram) – The tractogram to write.
path (str | Path) – The vtk or fib file; an existing file is overwritten.
binary (bool) – Binary (the default, smaller and faster) or ASCII.

Raises:

ValueError – If a data name is empty or has whitespace, a data array has more than 2 dimensions or a type VTK cannot store, or the tractogram is too large for VTK’s int32 indices.