write.nrrd: Write data and metadata to NRRD file or create a detached NRRD (nhdr) file.

Description

write.nrrd writes an array, vector or im3d object to a NRRD file. When x is an im3d object, appropriate spatial calibration fields are added to the header.

write.nrrd.header writes a nrrd header file.

write.nrrd.header.for.file makes a detached NRRD (nhdr) file that points at another image file on disk, making it NRRD compatible. This can be a convenient way to make NRRD inputs for other tools e.g. CMTK and also allows the same data block to pointed to by different nhdr files with different spatial calibration.

Usage

write.nrrd(
  x,
  file,
  enc = c("gzip", "raw", "text"),
  dtype = c("float", "byte", "short", "ushort", "int", "double"),
  header = attr(x, "header"),
  endian = .Platform$endian,
  datafile = NULL
)
write.nrrd.header(header, file)
write.nrrd.header.for.file(infile, outfile = NULL)

Arguments

x: Data to write as an array, vector or im3d object.
file: Character string naming an output file (a detached nrrd header when file has extension 'nhdr').
enc: One of three supported nrrd encodings ("gzip", "raw", "text")
dtype: The data type to write. One of "float","byte", "short", "ushort", "int", "double"
header: List containing fields of nrrd header - see Header section.
endian: One of "big" or "little". Defaults to .Platform$endian.
datafile: Optional name of separate file into which data should be written (see details).
infile, outfile: Path to input and output file for write.nrrd.header.for.file. If outfile is NULL (the default) then it will be set to <infilestem.nhdr>.

Detached NRRDs

NRRD files can be written in detached format (see https://teem.sourceforge.net/nrrd/format.html#detached) in which a text nhdr file is used to described the contents of a separate (usually binary) data file. This means that the nhdr file can be inspected and edited with a text editor, while the datablock can be in a completely raw format that can be opened even by programs that do not understand the NRRD format. Furthermore detached NRRD header files can be written to accompany non-NRRD image data so that it can be opened by nrrd readers.

If file has extension .nhdr or datafile is non-NULL, then write.nrrd will write a separate datafile. If datafile is set, then it is interpeted as specifying a path relative to the nhdr file. If datafile is not specified then default filenames will be chosen according to the encoding following the conventions of the teem library:

raw '<nhdrstem>.raw'
gzip '<nhdrstem>.raw.gz'
text '<nhdrstem>.ascii'

Data file paths

When a detached NRRD is written, the datafile can be specified either as relative or absolute path. Relative paths are strongly recommended - the best place is right next to the datafile. Relative paths are always specified with respect to the location of the nhdr file.

The datafile argument is not processed by write.nrrd so it is up to the caller to decide whether a relative or absolute path will be used.

For write.nrrd.header.for.file if outfile is not specified then the nhdr file will be placed next to the original image stack and the datafile field will therefore just be basename(infile). If outfile is specified explicitly, then datafile will be set to the full path in the infile argument. Therefore if you wish to specify outfile, you must set the current working directory (using setwd) to the location in which outfile will be written to ensure that the path to the datafile is correct. A future TODO would add the ability to convert an absolute datafile path to a relaive one (by finding the common path between datafile and nhdr folders).

Header