Learn R Programming

freesurferformats (version 1.0.2)

Read and Write 'FreeSurfer' Neuroimaging File Formats

Description

Provides functions to read and write neuroimaging data in various file formats, with a focus on 'FreeSurfer' formats. This includes, but is not limited to, the following file formats: 1) MGH/MGZ/NIFTI format files, which can contain multi-dimensional images or other data. Typically they contain time-series of three-dimensional brain scans acquired by magnetic resonance imaging (MRI). They can also contain vertex-wise measures of surface morphometry data. The MGH format is named after the Massachusetts General Hospital, and the MGZ format is a compressed version of the same format. 2) 'FreeSurfer' morphometry data files in binary 'curv' format. These contain vertex-wise surface measures, i.e., one scalar value for each vertex of a brain surface mesh. These are typically values like the cortical thickness or brain surface area at each vertex. 3) Annotation file format. This contains a brain surface parcellation derived from a cortical atlas. 4) Surface file format. Contains a brain surface mesh, given by a list of vertices and a list of faces.

Copy Link

Version

Install

install.packages('freesurferformats')

Monthly Downloads

1,307

Version

1.0.2

License

MIT + file LICENSE

Issues

Pull Requests

Stars

Forks

Maintainer

Tim Schc3<a4>fer

Last Published

September 8th, 2026

Functions in freesurferformats (1.0.2)

colortable.from.annot

Extract color lookup table (LUT) from annotation.
coord.to.key

Turn coordinate vector into string.
doapply.transform.mtx

Apply a spatial transformation matrix to the given coordinates.
delete_all_opt_data

Delete all data in the package cache.
fread3

Read 3-byte integer.
fs.patch

Constructor for fs.patch
fs.get.morph.file.format.from.filename

Determine morphometry file format from filename
closest.vert.to.point

Find vertex index closest to given query coordinate using Euclidean distance.
gifti_xml_add_global_metadata

Add metadata to GIFTI XML tree.
gifti_xml_write

Write XML tree to a gifti file.
check_file_size

Check that a file is large enough to contain the expected data payload.
get_max_alloc_bytes

Get the configured maximum allocation size in bytes.
filepath.ends.with

Check whether filepath ends with extension.
fixed.vec.format.int

Write fixed width integers to one or several lines.
get_opt_data_filepath

Access a single file from the package cache by its file name.
is.bvsmp

Check whether object is a bvsmp instance.
flip2D

Flip a 2D matrix.
flip3D

Flip a 3D array along an axis.
fs.get.morph.file.ext.for.format

Determine morphometry file extension from format
int.to.col.brainvoyager

Convert 32 bit integer to RGB color as described in Brainvoyager SRF file spec.
mgh.is.conformed

Determine whether an MGH volume is conformed.
mghheader

Constructor to init MGH header instance.
mghheader.ras2vox.tkreg

Compute ras2vox-tkreg matrix from basic MGH header fields.
mghheader.scanner2tkreg

Compute scanner-RAS 2 tkreg-RAS matrix from basic MGH header fields.
is.fs.surface

Check whether object is an fs.surface
is.fs.volume

Check whether object is an fs.volume
mghheader.is.conformed

Determine whether an MGH volume is conformed.
is.fs.label

Check whether object is an fs.label
get.slice.orientation

Compute MGH orientation string and direction
get.dti.trk.endianness

Determine endianness of TRK file.
faces.tris.to.quad

Convert tris faces to quad faces by simple merging.
fs.surface.to.tmesh3d

Get an rgl tmesh3d instance from a brain surface mesh.
nifti.datadim.to.dimfield

Compute NIFTI dim field for data dimension.
giftixml_add_labeltable_from_annot

Add a label tabel from an annotation to a GIFTI XML tree.
is.mghheader

Check whether object is an mghheader
gifti_writer

Write data to a gifti file.
linesplit.fixed

Split a string into fixed-length parts.
giftixml_add_labeltable_posneg

Add a standard label tabel for to a GIFTI XML tree.
fwrite3

Write 3-byte integer.
fileopen.gz.or.not

Get connection to a binary file, gz or not.
gifti_xml

Get GIFTI XML representation of data.
mghheader.primary.slice.direction

Compute MGH primary slice direction
guess.filename.is.gzipped

Guess whether a file is gzipped.
list_opt_data

Get file names available in package cache.
m44_to_quaternion

Compute quaternion representation of a rotation from a 4x4 rotation matrix.
has_pandoc

Check for pandoc availability on system.
mghheader.update.from.vox2ras

Update mghheader fields from vox2ras matrix.
mghheader.centervoxelRAS.from.firstvoxelRAS

Compute RAS coords of center voxel.
is.fs.annot

Check whether object is an fs.annot
mghheader.vox2ras.tkreg

Compute vox2ras-tkreg matrix from basic MGH header fields.
mghheader.vox2ras

Compute vox2ras matrix from basic MGH header fields.
mghheader.vox2vox

Compute vox2vox matrix between two volumes.
mghheader.is.ras.valid

Check whether header contains valid ras information
nifti.datadim.from.dimfield

Compute data dimensions from the 'dim' field of the NIFTI (v1 or v2) header.
read.fs.gca

Read FreeSurfer GCA file.
print.fs.label

Print description of a brain surface label.
mni152reg

Get fsaverage (MNI305) to MNI152 transformation matrix.
ni2header.template

Create a template NIFTI v2 header. You will have to adapt it for your use case.
print.fs.annot

Print description of a brain atlas or annotation.
nifti.field.check.length

Check whether vector has expected length.
mghheader.ras2vox

Compute ras2vox matrix from basic MGH header fields.
nifti.file.version

Determine NIFTI file version information and whether file is a NIFTI file.
nii1header.for.mgh

Create a NIFTI v1 header from the header information contained in an fs.volume instance.
nifti.dtypebitpix.info.from.mgh.dtype

Compute the 'datatype' and 'bitpix' fields used in the NIFTI1 header from an MGH/MGZ datatype code.
nifti.header.check

Perform basic sanity checks on NIFTI header data. These are in no way meant to be exhaustive.
read.element.counts.ply.header

Determine element counts from PLY file header.
read.fixed.char.binary

Read fixed length char, possibly containing embedded zeroes, from binary file.
nifti.transform.type.name

Get the name of the transform type from a form code.
read.fs.morph.gii

Read morphometry data file in GIFTI format.
read.fs.colortable

Read colortable file in FreeSurfer ASCII LUT format.
read.fs.curv

Read file in FreeSurfer curv format
ply.header.lines

Generate PLY format header lines
polygon.soup.to.indexed.mesh

Turn polygon soup into indexed mesh.
read.fs.surface.bvsrf

Read Brainvoyager srf format (.srf) mesh as surface.
read.fs.morph.txt

Read morphometry data from plain text file
read.fs.label

Read a label file.
read.fs.morph.asc

Read morphometry data from ASCII curv format file
mghheader.crs.orientation

Compute MGH volume orientation string.
ni2header.for.data

Create NIFTI v2 header suitable for given data.
nifti.field.check.nchar.max

Check whether character string fields have less than or equal to expected length.
ni1header.template

Create a template NIFTI v1 header. You will have to adapt it for your use case.
read.fs.morph.bvsmp

Read Brainvoyager vertex-wise statistical surface data from SMP file.
read.fs.surface.byu

Read mesh in BYU format.
nifti.file.uses.fshack

Determine whether a NIFTI file uses the FreeSurfer hack.
mghheader.tkreg2scanner

Compute tkreg-RAS to scanner-RAS matrix from basic MGH header fields.
ras.to.talairachras

Compute MNI talairach coordinates from RAS coords.
mri_dtype_numbytes

Get size of MRI dtype in bytes.
nifti.space.info

Compute NIFTI space unit info from xyzt_units header field.
print.fs.surface

Print description of a brain surface.
read.fs.patch

Read FreeSurfer binary or ASCII patch file.
nifti.dtype.info

Compute NIFTI v1 data type info from datatype and bitpix header field.
parse.stl.ascii.face

Parse a single ASCII STL face.
read.fs.surface.ply

Read Stanford PLY format mesh as surface.
read.fs.label.gii

Read a label from a GIFTI label/annotation file.
read.fs.morph.nii

Read morphometry data from FreeSurfer NIFTI format files, determine NIFTI version automatically.
read.fs.surface.geo

Read GEO format mesh as surface.
parse.transform.matrix.lines

Parse matrix from text file lines.
read.fs.morph.cifti

Read surface morphometry data from CIFTI dscalar files.
read.fs.patch.asc

Read FreeSurfer ASCII format patch.
read.fs.series.cifti

Read surface time series data from CIFTI dtseries files.
read.fs.surface.stl.ascii

Read surface mesh in STL ASCII format.
read.fs.surface.stl.bin

Read surface mesh in STL binary format.
ras.to.surfaceras

Translate RAS coordinates, as used in volumes by applying vox2ras, to surface RAS.
print.fs.volume

Print description of a brain volume.
read.dti.tsf

Read DTI tracking per-coord data from file in MRtrix 'TSF' format.
read.dti.tck

Read DTI tracking data from file in MRtrix 'TCK' format.
ni1header.for.data

Create NIFTI v1 header suitable for given data.
read.dti.trk

Read fiber tracks from Diffusion Toolkit in trk format.
nifti.time.info

Compute NIFTI time unit info from xyzt_units header field.
read.fs.weight

Read file in FreeSurfer weight or w format
read.fs.morph

Read morphometry data file in any FreeSurfer format.
print.fs.patch

Print description of a brain surface patch.
read.fs.surface.vtk

Read VTK ASCII format mesh as surface.
read.fs.morph.ni1

Read morphometry data from FreeSurfer NIFTI v1 format files.
read.fs.label.native

Read file in FreeSurfer label format
read.nifti2.data

Read raw data from NIFTI v2 file.
read.fs.parcellation.cifti

Read surface parcellation data from CIFTI dlabel files.
read.fs.surface.mz3

Read surface mesh in mz3 format, used by Surf-Ice.
sm1to0

Adapt spatial transformation matrix for 0-based indices.
read.fs.transform.lta

Load transformation matrix from a FreeSurfer linear transform array (LTA) file.
read.fs.morph.ni2

Read morphometry data from FreeSurfer NIFTI v2 format files.
read.fs.surface.off

Read Object File Format (OFF) mesh as surface.
read.fs.surface.stl

Read mesh in STL format, auto-detecting ASCII versus binary format version.
read.fs.transform.dat

Load transformation matrix from a tkregister dat file.
read.fs.surface.obj

Read OBJ format mesh as surface.
read.fs.surface.ico

Read ICO format mesh as surface.
read.mesh.brainvoyager

Read Brainvoyager srf format (.srf) mesh.
read.nifti2.header

Read NIFTI v2 header from file.
read_nisurface

Read a surface, based on the file path without extension.
read.fs.annot

Read file in FreeSurfer annotation format
read.fs.mgh

Read file in FreeSurfer MGH or MGZ format
read.fs.annot.gii

Read an annotation or label in GIFTI format.
read.fs.weight.asc

Read ASCII version of FreeSurfer weight file.
read.fs.transform

Load transformation matrix from a file.
read.smp.brainvoyager.v3

Read Brainvoyager statistical surface results from v3 SMP file.
surfaceras.to.talairach

Compute Talairach RAS for surface RAS (e.g., vertex coordinates).
rotate2D

Rotate a 2D matrix in 90 degree steps.
read.nifti1.header.internal

Read NIFTI v1 header from file (which may contain the FreeSurfer hack).
write.fs.morph

Write morphometry data in a format derived from the given file name.
read.fs.surface.asc

Read FreeSurfer ASCII format surface.
read.fs.transform.xfm

Load transformation matrix from an XFM file.
read.fs.surface

Read file in FreeSurfer surface format or various mesh formats.
stl.format.file.is.ascii

Guess whether a mesh file in STL format is the ASCII or the binary version.
read.smp.brainvoyager.v4or5

Read Brainvoyager statistical surface results from v4 or v5 SMP file.
read_nisurfacefile

S3 method to read a neuroimaging surface file.
surfaceras.to.ras

Translate surface RAS coordinates, as used in surface vertices and surface labels, to volume RAS.
readcolortable_oldformat

Read binary colortable in old format.
write.fs.morph.ni1

Write morphometry data in NIFTI v1 format.
write.fs.curv

Write file in FreeSurfer curv format
write.fs.colortable

Write colortable file in FreeSurfer ASCII LUT format.
vertexdists.to.point

Compute Euclidean distance from all mesh vertices to given point.
read.fs.volume

Read volume file in MGH, MGZ or NIFTI format
sm0to1

Adapt spatial transformation matrix for 1-based indices.
read_nisurfacefile.gifti

Read a gifti file as a surface.
scann

Scan exactly n values from source string.
read_safe_bin

Safe wrapper around readBin that verifies the number of elements read.
write.fs.annot.gii

Write annotation to GIFTI file.
write.fs.volume

Write an fs.volume instance to a file in MGH, MGZ or NIFTI v1 format.
write.fs.morph.ni2

Write morphometry data in NIFTI v2 format.
read.nifti2.header.internal

Read NIFTI v2 header from file.
write.fs.surface.asc

Write mesh to file in FreeSurfer ASCII surface format
write.fs.annot

Write annotation to binary file.
xml_node_gifti_label

Create XML GIFTI Label node.
write.fs.mgh

Write file in FreeSurfer MGH or MGZ format
xml_node_gifti_coordtransform

Create XML GIFTI CoordinateSystemTransformMatrix node.
write.fs.surface.bvsrf

Write surface to Brainvoyager SRF file.
write.fs.label

Write vertex indices to file in FreeSurfer label format
write.fs.surface.off

Write mesh to file in Object File Format (.off)
write.fs.surface.off.ply2

Write mesh to file in Object File Format (.off) or PLY2 format.
write.fs.label.gii

Write a binary surface label in GIFTI format.
write.nifti2

Write header and data to a file in NIFTI v2 format.
write.nifti1

Write header and data to a file in NIFTI v1 format.
xml_node_gifti_label_table

Create XML GIFTI LabelTable node.
xml_node_gifti_label_table_from_annot

Compute LabelTable node from annotation.
read.fs.surface.gii

Read GIFTI format mesh as surface.
read.fs.volume.nii

Turn a 3D or 4D oro.nifti instance into an fs.volume instance with complete header.
read_nisurfacefile.fsascii

Read a FreeSurfer ASCII surface file.
readable.files

Find files with the given base name and extensions that exist.
read.smp.brainvoyager

Read Brainvoyager statistical surface results from SMP file.
talairachras.to.ras

Compute MNI talairach coordinates from RAS coords.
read.nifti1.data

Read raw NIFTI v1 data from file (which may contain the FreeSurfer hack).
read.nifti1.header

Read NIFTI v1 header from file (which may contain the FreeSurfer hack).
translate.mri.dtype

Translate between code and name of MRI data types.
read_nisurfacefile.fsnative

Read a FreeSurfer ASCII surface file.
write.fs.surface.vtk

Write mesh to file in VTK ASCII format
write.fs.morph.gii

Write morphometry data in GIFTI format.
write.fs.weight.asc

Write file in FreeSurfer weight ASCII format
write.fs.morph.asc

Write file in FreeSurfer ASCII curv format
write.fs.surface

Write mesh to file in FreeSurfer binary surface format
readcolortable

Read binary colortable in v2 format.
read.smp.brainvoyager.v1or2

Read Brainvoyager statistical surface results from v1 or v2 SMP file.
write.fs.surface.byu

Write mesh to file in BYU ASCII format.
write.fs.surface.mz3

Write mesh to file in mz3 binary format.
write.fs.surface.obj

Write mesh to file in Wavefront object (.obj) format
write.fs.weight

Write file in FreeSurfer weight format
write.fs.surface.ply

Write mesh to file in PLY format (.ply)
rotate3D

Rotate a 3D array in 90 degree steps.
write.fs.morph.txt

Write curv data to file in simple text format
rotate90

Rotate 2D matrix clockwise in 90 degree steps.
write.atlas.to.lut.and.csv

Write a brain atlas to a colortable (LUT) file and a per-vertex label file.
write.fs.patch

Write a surface patch
write.smp.brainvoyager

Write a brainvoyager SMP file.
write.fs.surface.gii

Write mesh to file in GIFTI surface format
write.smp.brainvoyager.v2

Write a brainvoyager v2 SMP file.
write.fs.morph.smp

Write morphometry data in Brainvoyager SMP format.
xml_node_gifti_MD

Create XML GIFTI metadata node.
write.fs.surface.ply2

Write mesh to file in PLY2 File Format (.ply2)
vertex.euclid.dist

Compute Euclidean distance between two vertices v1 and v2.
write.smp.brainvoyager.v3or4or5

Write a brainvoyager v3, v4 or v5 SMP file.
validate_allocation_size

Validate that a requested allocation does not exceed the safety limit.
check.dtype.for.data

Check whether the dtype is suitable for the data.
annot.max.region.idx

Get max region index of an fs.annot instance.
cdata

Create CDATA element string from string.
check_all_finite

Check that a numeric vector or matrix contains only finite values.
adjust.face.indices.to

Adjust integer matrix to target min value.
atlas.from.lut.and.csv

Construct a brain atlas from a colortable (LUT) file and a per-vertex label file.
bvsmp

Create new bvsmp instance encoding morph data for Brainvoyager.
download_opt_data

Download optional data for the freesurferformats package.
faces.quad.to.tris

Convert quadrangular faces or polygons to triangular ones.
check_data_and_settings_consistency

Warn about common errors in combining data and datatype.
assert.surface

Stop unless surf is an fs.surface
annot.unique

Make the region names and indices unique across hemispheres for a parcellation.
euclidian.dist

Compute Euclidean distance.
.read.dti.tcktsf

.read.dti.tcktsf