nifti1_io
Classes | Macros | Typedefs | Enumerations | Functions
nifti1_io.h File Reference

Data structures for using nifti1_io API. More...

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <math.h>
#include <ctype.h>
#include "nifti1.h"
#include <znzlib.h>
Include dependency graph for nifti1_io.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  mat44
 
struct  mat33
 
struct  nifti_image
 High level data structure for open nifti datasets in the nifti1_io API. Note that this structure is not part of the nifti1 format definition; it is used to implement one API for reading/writing formats in the nifti1 format. More...
 
struct  nifti_brick_list
 
struct  nifti_analyze75
 

Macros

#define DONT_INCLUDE_ANALYZE_STRUCT   /*** not needed herein ***/
 
#define NIFTI_L2R   1 /* Left to Right */
 
#define NIFTI_R2L   2 /* Right to Left */
 
#define NIFTI_P2A   3 /* Posterior to Anterior */
 
#define NIFTI_A2P   4 /* Anterior to Posterior */
 
#define NIFTI_I2S   5 /* Inferior to Superior */
 
#define NIFTI_S2I   6 /* Superior to Inferior */
 
#define NIFTI_ECODE_IGNORE   0 /* changed from UNKNOWN, 29 June 2005 */
 
#define NIFTI_ECODE_DICOM   2 /* intended for raw DICOM attributes */
 
#define NIFTI_ECODE_AFNI
 
#define NIFTI_ECODE_COMMENT   6 /* plain ASCII text only */
 
#define NIFTI_ECODE_XCEDE
 
#define NIFTI_ECODE_JIMDIMINFO
 
#define NIFTI_ECODE_WORKFLOW_FWDS
 
#define NIFTI_ECODE_FREESURFER   14 /* http://surfer.nmr.mgh.harvard.edu */
 
#define NIFTI_ECODE_PYPICKLE
 
#define NIFTI_ECODE_MIND_IDENT   18 /* Vishal Patel: vishal.patel@ucla.edu*/
 
#define NIFTI_ECODE_B_VALUE   20
 
#define NIFTI_ECODE_SPHERICAL_DIRECTION   22
 
#define NIFTI_ECODE_DT_COMPONENT   24
 
#define NIFTI_ECODE_SHC_DEGREEORDER   26 /* end LONI MiND codes */
 
#define NIFTI_ECODE_VOXBO   28 /* Dan Kimberg: www.voxbo.org */
 
#define NIFTI_ECODE_CARET
 
#define NIFTI_MAX_ECODE   30 /******* maximum extension code *******/
 
#define NIFTI_FTYPE_ANALYZE   0
 
#define NIFTI_FTYPE_NIFTI1_1   1
 
#define NIFTI_FTYPE_NIFTI1_2   2
 
#define NIFTI_FTYPE_ASCII   3
 
#define NIFTI_MAX_FTYPE   3 /* this should match the maximum code */
 

Typedefs

typedef enum _analyze75_orient_code analyze_75_orient_code
 

Enumerations

enum  _analyze75_orient_code {
  a75_transverse_unflipped = 0, a75_coronal_unflipped = 1, a75_sagittal_unflipped = 2, a75_transverse_flipped = 3,
  a75_coronal_flipped = 4, a75_sagittal_flipped = 5, a75_orient_unknown = 6
}
 

Functions

char const * nifti_datatype_string (int dt)
 
char const * nifti_units_string (int uu)
 
char const * nifti_intent_string (int ii)
 
char const * nifti_xform_string (int xx)
 
char const * nifti_slice_string (int ss)
 
char const * nifti_orientation_string (int ii)
 
int nifti_is_inttype (int dt)
 
mat44 nifti_mat44_inverse (mat44 R)
 
mat33 nifti_mat33_inverse (mat33 R)
 
mat33 nifti_mat33_polar (mat33 A)
 
float nifti_mat33_rownorm (mat33 A)
 
float nifti_mat33_colnorm (mat33 A)
 
float nifti_mat33_determ (mat33 R)
 
mat33 nifti_mat33_mul (mat33 A, mat33 B)
 
void nifti_swap_2bytes (size_t n, void *ar)
 
void nifti_swap_4bytes (size_t n, void *ar)
 
void nifti_swap_8bytes (size_t n, void *ar)
 
void nifti_swap_16bytes (size_t n, void *ar)
 
void nifti_swap_Nbytes (size_t n, int siz, void *ar)
 
int nifti_datatype_is_valid (int dtype, int for_nifti)
 
int nifti_datatype_from_string (const char *name)
 
const char * nifti_datatype_to_string (int dtype)
 
int nifti_get_filesize (const char *pathname)
 
void swap_nifti_header (struct nifti_1_header *h, int is_nifti)
 
void old_swap_nifti_header (struct nifti_1_header *h, int is_nifti)
 
int nifti_swap_as_analyze (nifti_analyze75 *h)
 
nifti_imagenifti_image_read_bricks (const char *hname, int nbricks, const int *blist, nifti_brick_list *NBL)
 
int nifti_image_load_bricks (nifti_image *nim, int nbricks, const int *blist, nifti_brick_list *NBL)
 
void nifti_free_NBL (nifti_brick_list *NBL)
 
nifti_imagenifti_image_read (const char *hname, int read_data)
 Read a nifti header and optionally the data, creating a nifti_image. More...
 
int nifti_image_load (nifti_image *nim)
 Load the image blob into a previously initialized nifti_image. More...
 
void nifti_image_unload (nifti_image *nim)
 
void nifti_image_free (nifti_image *nim)
 
int nifti_read_collapsed_image (nifti_image *nim, const int dims [8], void **data)
 
int nifti_read_subregion_image (nifti_image *nim, int *start_index, int *region_size, void **data)
 
void nifti_image_write (nifti_image *nim)
 
void nifti_image_write_bricks (nifti_image *nim, const nifti_brick_list *NBL)
 
void nifti_image_infodump (const nifti_image *nim)
 
void nifti_disp_lib_hist (void)
 
void nifti_disp_lib_version (void)
 
int nifti_disp_matrix_orient (const char *mesg, mat44 mat)
 
int nifti_disp_type_list (int which)
 
char * nifti_image_to_ascii (const nifti_image *nim)
 
nifti_imagenifti_image_from_ascii (const char *str, int *bytes_read)
 
size_t nifti_get_volsize (const nifti_image *nim)
 
int nifti_set_filenames (nifti_image *nim, const char *prefix, int check, int set_byte_order)
 
char * nifti_makehdrname (const char *prefix, int nifti_type, int check, int comp)
 
char * nifti_makeimgname (const char *prefix, int nifti_type, int check, int comp)
 
int is_nifti_file (const char *hname)
 
char * nifti_find_file_extension (const char *name)
 
int nifti_is_complete_filename (const char *fname)
 
int nifti_validfilename (const char *fname)
 
int disp_nifti_1_header (const char *info, const nifti_1_header *hp)
 
void nifti_set_debug_level (int level)
 
void nifti_set_skip_blank_ext (int skip)
 
void nifti_set_allow_upper_fext (int allow)
 
int valid_nifti_brick_list (nifti_image *nim, int nbricks, const int *blist, int disp_error)
 
znzFile nifti_image_open (const char *hname, char *opts, nifti_image **nim)
 Read in NIFTI-1 or ANALYZE-7.5 file (pair) header information into a nifti_image struct. More...
 
znzFile nifti_image_write_hdr_img (nifti_image *nim, int write_data, const char *opts)
 
znzFile nifti_image_write_hdr_img2 (nifti_image *nim, int write_opts, const char *opts, znzFile imgfile, const nifti_brick_list *NBL)
 
size_t nifti_read_buffer (znzFile fp, void *datatptr, size_t ntot, nifti_image *nim)
 
int nifti_write_all_data (znzFile fp, nifti_image *nim, const nifti_brick_list *NBL)
 
size_t nifti_write_buffer (znzFile fp, const void *buffer, size_t numbytes)
 
nifti_imagenifti_read_ascii_image (znzFile fp, char *fname, int flen, int read_data)
 
znzFile nifti_write_ascii_image (nifti_image *nim, const nifti_brick_list *NBL, const char *opts, int write_data, int leave_open)
 
void nifti_datatype_sizes (int datatype, int *nbyper, int *swapsize)
 
void nifti_mat44_to_quatern (mat44 R, float *qb, float *qc, float *qd, float *qx, float *qy, float *qz, float *dx, float *dy, float *dz, float *qfac)
 
mat44 nifti_quatern_to_mat44 (float qb, float qc, float qd, float qx, float qy, float qz, float dx, float dy, float dz, float qfac)
 
mat44 nifti_make_orthog_mat44 (float r11, float r12, float r13, float r21, float r22, float r23, float r31, float r32, float r33)
 
int nifti_short_order (void)
 
void nifti_mat44_to_orientation (mat44 R, int *icod, int *jcod, int *kcod)
 
char * nifti_findhdrname (const char *fname)
 
char * nifti_findimgname (const char *fname, int nifti_type)
 
int nifti_is_gzfile (const char *fname)
 
char * nifti_makebasename (const char *fname)
 
struct nifti_1_header nifti_convert_nim2nhdr (const nifti_image *nim)
 
nifti_1_headernifti_make_new_header (const int arg_dims[], int arg_dtype)
 
nifti_1_headernifti_read_header (const char *hname, int *swapped, int check)
 
nifti_imagenifti_copy_nim_info (const nifti_image *src)
 
nifti_imagenifti_make_new_nim (const int dims[], int datatype, int data_fill)
 
nifti_imagenifti_simple_init_nim (void)
 
nifti_imagenifti_convert_nhdr2nim (struct nifti_1_header nhdr, const char *fname)
 
int nifti_hdr_looks_good (const nifti_1_header *hdr)
 
int nifti_is_valid_datatype (int dtype)
 
int nifti_is_valid_ecode (int ecode)
 
int nifti_nim_is_valid (nifti_image *nim, int complain)
 
int nifti_nim_has_valid_dims (nifti_image *nim, int complain)
 
int is_valid_nifti_type (int nifti_type)
 
int nifti_test_datatype_sizes (int verb)
 
int nifti_type_and_names_match (nifti_image *nim, int show_warn)
 
int nifti_update_dims_from_array (nifti_image *nim)
 
void nifti_set_iname_offset (nifti_image *nim)
 
int nifti_set_type_from_names (nifti_image *nim)
 
int nifti_add_extension (nifti_image *nim, const char *data, int len, int ecode)
 
int nifti_compiled_with_zlib (void)
 
int nifti_copy_extensions (nifti_image *nim_dest, const nifti_image *nim_src)
 
int nifti_free_extensions (nifti_image *nim)
 
int * nifti_get_intlist (int nvals, const char *str)
 
char * nifti_strdup (const char *str)
 
int valid_nifti_extensions (const nifti_image *nim)
 

Detailed Description

Data structures for using nifti1_io API.

Macro Definition Documentation

◆ NIFTI_ECODE_AFNI

#define NIFTI_ECODE_AFNI
Value:
4 /* Robert W Cox: rwcox@nih.gov
http://afni.nimh.nih.gov/afni */

◆ NIFTI_ECODE_CARET

#define NIFTI_ECODE_CARET
Value:
30 /* John Harwell: john@brainvis.wustl.edu
http://brainvis.wustl.edu/wiki
/index.php/Caret:Documentation
:CaretNiftiExtension */

◆ NIFTI_ECODE_JIMDIMINFO

#define NIFTI_ECODE_JIMDIMINFO
Value:
10 /* Mark A Horsfield:
mah5@leicester.ac.uk
http://someplace/something */

◆ NIFTI_ECODE_PYPICKLE

#define NIFTI_ECODE_PYPICKLE
Value:
16 /* embedded Python objects
http://niftilib.sourceforge.net
/pynifti */

◆ NIFTI_ECODE_WORKFLOW_FWDS

#define NIFTI_ECODE_WORKFLOW_FWDS
Value:
12 /* Kate Fissell: fissell@pitt.edu
http://kraepelin.wpic.pitt.edu
/~fissell/NIFTI_ECODE_WORKFLOW_FWDS
/NIFTI_ECODE_WORKFLOW_FWDS.html */

◆ NIFTI_ECODE_XCEDE

#define NIFTI_ECODE_XCEDE
Value:
8 /* David B Keator: dbkeator@uci.edu
http://www.nbirn.net/Resources
/Users/Applications/
/xcede/index.htm */

Function Documentation

◆ disp_nifti_1_header()

int disp_nifti_1_header ( const char *  info,
const nifti_1_header hp 
)

display the contents of the nifti_1_header (send to stdout)

Parameters
infoif non-NULL, print this character string
hppointer to nifti_1_header

◆ is_nifti_file()

int is_nifti_file ( const char *  hname)

Determine if this is a NIFTI-formatted file.

Returns
0 if file looks like ANALYZE 7.5 [checks sizeof_hdr field == 348] 1 if file marked as NIFTI (header+data in 1 file) 2 if file marked as NIFTI (header+data in 2 files) -1 if it can't tell, file doesn't exist, etc.

◆ is_valid_nifti_type()

int is_valid_nifti_type ( int  nifti_type)

check whether the given type is on the "approved" list

The code is valid if it is non-negative, and does not exceed NIFTI_MAX_FTYPE.

Returns
1 if nifti_type is valid, 0 otherwise
See also
NIFTI_FTYPE_* codes in nifti1_io.h

◆ nifti_add_extension()

int nifti_add_extension ( nifti_image nim,
const char *  data,
int  len,
int  ecode 
)

nifti_add_extension - add an extension, with a copy of the data

Add an extension to the nim->ext_list array. Fill this extension with a copy of the data, noting the length and extension code.

Parameters
nim- nifti_image to add extension to
data- raw extension data
length- length of raw extension data
ecode- extension code
See also
extension codes NIFTI_ECODE_* in nifti1_io.h
nifti_free_extensions, valid_nifti_extensions, nifti_copy_extensions
Returns
0 on success, -1 on error (and free the entire list)

◆ nifti_compiled_with_zlib()

int nifti_compiled_with_zlib ( void  )

return whether the given library was compiled with HAVE_ZLIB set

◆ nifti_convert_nhdr2nim()

nifti_image* nifti_convert_nhdr2nim ( struct nifti_1_header  nhdr,
const char *  fname 
)

convert a nifti_1_header into a nift1_image

Returns
an allocated nifti_image, or NULL on failure
  • check if we must swap bytes
  • determine if this is a NIFTI-1 compliant header
  • in analyze75, the orient code is at the same address as qform_code, but it's just one byte the qform_code will be zero, at which point you can check analyze75_orient if you care to.
  • set bad grid spacings to 1.0
  • set dimensions of data array
  • set the type of data in voxels and how many bytes per voxel
  • set the grid spacings
  • compute qto_xyz transformation from pixel indexes (i,j,k) to (x,y,z)
  • if not nifti or qform_code <= 0, use grid spacing for qto_xyz
  • else NIFTI: use the quaternion-specified transformation
  • load inverse transformation (x,y,z) -> (i,j,k)
  • load sto_xyz affine transformation, if present
  • if not nifti or sform_code <= 0, then no sto transformation
  • else set the sto transformation from srow_*[]
  • set miscellaneous NIFTI stuff
  • set Miscellaneous ANALYZE stuff
  • set ioff from vox_offset (but at least sizeof(header))
  • deal with file names if set

◆ nifti_convert_nim2nhdr()

struct nifti_1_header nifti_convert_nim2nhdr ( const nifti_image nim)

convert a nifti_image structure to a nifti_1_header struct

No allocation is done, this should be used via structure copy. As in:

nifti_1_header my_header;
my_header = nifti_convert_nim2nhdr(my_nim_pointer);
  • load the ANALYZE-7.5 generic parts of the header struct
  • Load NIFTI specific stuff into the header

◆ nifti_copy_nim_info()

nifti_image* nifti_copy_nim_info ( const nifti_image src)

copy the nifti_image structure, without data

Duplicate the structure, including fname, iname and extensions. Leave the data pointer as NULL.

◆ nifti_datatype_from_string()

int nifti_datatype_from_string ( const char *  name)

Given a NIFTI_TYPE string, such as "NIFTI_TYPE_INT16", return the corresponding integral type code. The type code is the macro value defined in nifti1.h.

◆ nifti_datatype_is_valid()

int nifti_datatype_is_valid ( int  dtype,
int  for_nifti 
)

Determine whether dtype is a valid NIFTI_TYPE.

DT_UNKNOWN is considered invalid

The only difference 'for_nifti' makes is that DT_BINARY should be invalid for a NIfTI dataset.

◆ nifti_datatype_sizes()

void nifti_datatype_sizes ( int  datatype,
int *  nbyper,
int *  swapsize 
)

Given a datatype code, set number of bytes per voxel and the swapsize.

Parameters
datatypenifti1 datatype code
nbyperpointer to return value: number of bytes per voxel
swapsizepointer to return value: size of swap blocks
Returns
appropriate values at nbyper and swapsize

The swapsize is set to 0 if this datatype doesn't ever need swapping.

See also
NIFTI1_DATATYPES in nifti1.h

◆ nifti_datatype_string()

char const* nifti_datatype_string ( int  dt)

Return a pointer to a string holding the name of a NIFTI datatype.

Parameters
dtNIfTI-1 datatype
Returns
pointer to static string holding the datatype name
Warning
Do not free() or modify this string! It points to static storage.
See also
NIFTI1_DATATYPES group in nifti1.h

◆ nifti_datatype_to_string()

const char* nifti_datatype_to_string ( int  dtype)

Given a NIFTI_TYPE value, such as NIFTI_TYPE_INT16, return the corresponding macro label as a string. The dtype code is the macro value defined in nifti1.h.

◆ nifti_disp_lib_hist()

void nifti_disp_lib_hist ( void  )

display the nifti library module history (via stdout)

◆ nifti_disp_lib_version()

void nifti_disp_lib_version ( void  )

display the nifti library version (via stdout)

◆ nifti_disp_matrix_orient()

int nifti_disp_matrix_orient ( const char *  mesg,
mat44  mat 
)

display the orientation from the quaternian fields

Parameters
mesgif non-NULL, display this message first
matthe matrix to convert to "nearest" orientation
Returns
-1 if results cannot be determined, 0 if okay

◆ nifti_disp_type_list()

int nifti_disp_type_list ( int  which)

Display the nifti_type_list table.

if which == 1 : display DT_* if which == 2 : display NIFTI_TYPE* else : display all

◆ nifti_find_file_extension()

char* nifti_find_file_extension ( const char *  name)

check the end of the filename for a valid nifti extension

Valid extensions are currently .nii, .hdr, .img, .nia, or any of them followed by .gz. Note that '.' is part of the extension.

Uppercase extensions are also valid, but not mixed case.

Returns
a pointer to the extension substring within the original function input parameter name, or NULL if not found. Note that if the input parameter is is immutabale (i.e. a const char *) then this function performs an implicit casting away of the mutability constraint and the return parameter will appear as a mutable even though it is part of the immuttable string.

◆ nifti_findhdrname()

char* nifti_findhdrname ( const char *  fname)

check current directory for existing header file

Returns
filename of header on success and NULL if no appropriate file could be found

If fname has an uppercase extension, check for uppercase files.

NB: it allocates memory for hdrname which should be freed when no longer required

  • check input file(s) for sanity
  • return filename if it has a valid extension and exists (except if it is an .img file (and maybe .gz))
  • if .img, look for .hdr, .hdr.gz, .nii, .nii.gz, in that order
  • else, look for .nii, .nii.gz, .hdr, .hdr.gz, in that order
  • if nothing has been found, return NULL

◆ nifti_findimgname()

char* nifti_findimgname ( const char *  fname,
int  nifti_type 
)

check current directory for existing image file

Parameters
fnamefilename to check for nifti_type for dataset - this determines whether to first check for ".nii" or ".img" (since both may exist)
Returns
filename of data/img file on success and NULL if no appropriate file could be found

If fname has a valid, uppercase extension, apply all extensions as uppercase.

NB: it allocates memory for the image filename, which should be freed when no longer required

  • test for .nii and .img (don't assume input type from image type)
  • if nifti_type = 1, check for .nii first, else .img first
  • if nothing has been found, return NULL

◆ nifti_free_extensions()

int nifti_free_extensions ( nifti_image nim)

free the nifti extensions

  • If any edata pointer is set in the extension list, free() it.
  • Free ext_list, if it is set.
  • Clear num_ext and ext_list from nim.
Returns
0 on success, -1 on error
See also
nifti_add_extension, nifti_copy_extensions

◆ nifti_free_NBL()

void nifti_free_NBL ( nifti_brick_list NBL)

nifti_free_NBL - free all pointers and clear structure

note: this does not presume to free the structure pointer

◆ nifti_get_filesize()

int nifti_get_filesize ( const char *  pathname)

return the size of a file, in bytes

Returns
size of file on success, -1 on error or no file

changed to return int, -1 means no file or error 20 Dec 2004 [rickr]

◆ nifti_get_intlist()

int* nifti_get_intlist ( int  nvals,
const char *  str 
)

Get an integer list in the range 0..(nvals-1), from the character string str. If we call the output pointer fred, then fred[0] = number of integers in the list (> 0), and fred[i] = i-th integer in the list for i=1..fred[0]. If on return, fred == NULL or fred[0] == 0, then something is wrong, and the caller must deal with that.

Syntax of input string:

  • initial '{' or '[' is skipped, if present
  • ends when '}' or ']' or end of string is found
  • contains entries separated by commas
  • entries have one of these forms:
    • a single number
    • a dollar sign '$', which means nvals-1
    • a sequence of consecutive numbers in the form "a..b" or "a-b", where "a" and "b" are single numbers (or '$')
    • a sequence of evenly spaced numbers in the form "a..b(c)" or "a-b(c)", where "c" encodes the step
  • Example: "[2,7..4,3..9(2)]" decodes to the list 2 7 6 5 4 3 5 7 9
  • entries should be in the range 0..nvals-1

(borrowed, with permission, from thd_intlist.c)

  • for each sub-selector until end of input...
  • get starting value
  • if that's it for this sub-selector, add one value to list
  • otherwise, must have '..' or '-' as next inputs
  • get ending value for loop now
  • set default loop step
  • check if we have a non-default loop step
  • add values to output
  • check if we have a comma to skip over

◆ nifti_get_volsize()

size_t nifti_get_volsize ( const nifti_image nim)

return the total volume size, in bytes

This is computed as nvox * nbyper.

◆ nifti_hdr_looks_good()

int nifti_hdr_looks_good ( const nifti_1_header hdr)

decide if this nifti_1_header structure looks reasonable

Check dim[0], dim[1], sizeof_hdr, and datatype. Check magic string for "n+1". Maybe more tests will follow.

Returns
1 if the header seems valid, 0 otherwise
See also
nifti_nim_is_valid, valid_nifti_extensions

◆ nifti_image_free()

void nifti_image_free ( nifti_image nim)

free 'everything' about a nifti_image struct (including the passed struct)

free (only fields which are not NULL):

  • fname and iname
  • data
  • any ext_list[i].edata
  • ext_list
  • nim

◆ nifti_image_from_ascii()

nifti_image* nifti_image_from_ascii ( const char *  str,
int *  bytes_read 
)

Take an XML-ish ASCII string and create a NIFTI image header to match.

NULL is returned if enough information isn't present in the input string.

  • The image data can later be loaded with nifti_image_load().
  • The struct returned here can be liberated with nifti_image_free().
  • Not a lot of error checking is done here to make sure that the input values are reasonable!

◆ nifti_image_infodump()

void nifti_image_infodump ( const nifti_image nim)

Print to stdout some info about a nifti_image struct.

◆ nifti_image_load()

int nifti_image_load ( nifti_image nim)

Load the image blob into a previously initialized nifti_image.

  • If not yet set, the data buffer is allocated with calloc().
  • The data buffer will be byteswapped if necessary.
  • The data buffer will not be scaled.

This function is used to read the image from disk. It should be used after a function such as nifti_image_read(), so that the nifti_image structure is already initialized.

Parameters
nimpointer to a nifti_image (previously initialized)
Returns
0 on success, -1 on failure
See also
nifti_image_read, nifti_image_free, nifti_image_unload
  • open the file and position the FILE pointer
  • if the data pointer is not yet set, get memory space for the image
  • now that everything is set up, do the reading
  • close the file

◆ nifti_image_load_bricks()

int nifti_image_load_bricks ( nifti_image nim,
int  nbricks,
const int *  blist,
nifti_brick_list NBL 
)

Load the image data from disk into an already-prepared image struct.

Parameters
nim- initialized nifti_image, without data
nbricks- the length of blist (must be 0 if blist is NULL)
blist- an array of xyz volume indices to read (can be NULL)
NBL- pointer to struct where resulting data will be stored

If blist is NULL, read all sub-bricks.

Returns
the number of loaded bricks (NBL->nbricks), 0 on failure, < 0 on error

NOTE: it is likely that another function will copy the data pointers out of NBL, in which case the only pointer the calling function will want to free is NBL->bricks (not each NBL->bricks[i]).

◆ nifti_image_open()

znzFile nifti_image_open ( const char *  hname,
char *  opts,
nifti_image **  nim 
)

Read in NIFTI-1 or ANALYZE-7.5 file (pair) header information into a nifti_image struct.

znzFile nifti_image_open( char *hname, char *opts , nifti_image **nim)

  • The image data is not read from disk (it may be read later using nifti_image_load(), for example).
  • The image data will be stored in whatever data format the input data is; no scaling will be applied.
  • DT_BINARY data is not supported.
  • nifti_image_free() can be used to delete the returned struct, when you are done with it.
Parameters
hnamefilename of dataset .hdr or .nii file
optsoptions string for opening the header file
nimpointer to pointer to nifti_image struct (this routine allocates the nifti_image struct)
Returns
file pointer (gzippable) to the file with the image data, ready for reading.
NULL if something fails badly.
See also
nifti_image_load, nifti_image_free

◆ nifti_image_read()

nifti_image* nifti_image_read ( const char *  hname,
int  read_data 
)

Read a nifti header and optionally the data, creating a nifti_image.

  • The data buffer will be byteswapped if necessary.
  • The data buffer will not be scaled.
  • The data buffer is allocated with calloc().
Parameters
hnamefilename of the nifti dataset
read_dataFlag, true=read data blob, false=don't read blob.
Returns
A pointer to the nifti_image data structure.
See also
nifti_image_free, nifti_free_extensions, nifti_image_read_bricks
  • determine filename to use for header
  • read binary header
  • convert all nhdr fields to nifti_image fields
  • check for extensions (any errors here means no extensions)
  • read the data if desired, then bug out

◆ nifti_image_read_bricks()

nifti_image* nifti_image_read_bricks ( const char *  hname,
int  nbricks,
const int *  blist,
nifti_brick_list NBL 
)

nifti_image_read_bricks - read nifti data as array of bricks

                             13 Dec 2004 [rickr]
Parameters
hname- filename of dataset to read (must be valid)
nbricks- number of sub-bricks to read (if blist is valid, nbricks must be > 0)
blist- list of sub-bricks to read (can be NULL; if NULL, read complete dataset)
NBL- pointer to empty nifti_brick_list struct (must be a valid pointer)
Returns

nim - same as nifti_image_read, but nim->nt = NBL->nbricks (or nt*nu*nv*nw) nim->nu,nv,nw = 1 nim->data = NULL
NBL - filled with data volumes

By default, this function will read the nifti dataset and break the data into a list of nt*nu*nv*nw sub-bricks, each having size nx*ny*nz elements. That is to say, instead of reading the entire dataset as a single array, break it up into sub-bricks (volumes), each of size nx*ny*nz elements.

Note: in the returned nifti_image, nu, nv and nw will always be 1. The intention of this function is to collapse the dataset into a single array of volumes (of length nbricks or nt*nu*nv*nw).

If 'blist' is valid, it is taken to be a list of sub-bricks, of length 'nbricks'. The data will still be separated into sub-bricks of size nx*ny*nz elements, but now 'nbricks' sub-bricks will be returned, of the caller's choosing via 'blist'.

E.g. consider a dataset with 12 sub-bricks (numbered 0..11), and the following code:

{ nifti_brick_list   NB_orig, NB_select;
  nifti_image      * nim_orig, * nim_select;
  int                blist[5] = { 7, 0, 5, 5, 9 };
  nim_orig   = nifti_image_read_bricks("myfile.nii", 0, NULL,  &NB_orig);
  nim_select = nifti_image_read_bricks("myfile.nii", 5, blist, &NB_select);
}

Here, nim_orig gets the entire dataset, where NB_orig.nbricks = 12. But nim_select has NB_select.nbricks = 5.

Note that the first case is not quite the same as just calling the nifti_image_read function, as here the data is separated into sub-bricks.

Note that valid blist elements are in [0..nt*nu*nv*nw-1], or written [ 0 .. (dim[4]*dim[5]*dim[6]*dim[7] - 1) ].

Note that, as is the case with all of the reading functions, the data will be allocated, read in, and properly byte-swapped, if necessary.

See also
nifti_image_load_bricks, nifti_free_NBL, valid_nifti_brick_list, nifti_image_read

◆ nifti_image_to_ascii()

char* nifti_image_to_ascii ( const nifti_image nim)

Dump the information in a NIFTI image header to an XML-ish ASCII string that can later be converted back into a NIFTI header in nifti_image_from_ascii().

The resulting string can be free()-ed when you are done with it.

Strings that we don't control (filenames, etc.) that might contain "weird" characters (like quotes) are "escaped":

  • A few special characters are replaced by XML-style escapes, using the function escapize_string().
  • On input, function unescape_string() reverses this process.
  • The result is that the NIFTI ASCII-format header is XML-compliant.

◆ nifti_image_unload()

void nifti_image_unload ( nifti_image nim)

Unload the data in a nifti_image struct, but keep the metadata.

◆ nifti_image_write()

void nifti_image_write ( nifti_image nim)

Write a nifti_image to disk.

Since data is properly byte-swapped upon reading, it is assumed to be in the byte-order of the current CPU at write time. Thus, nim->byte_order should match that of the current CPU. Note that the nifti_set_filenames() function takes the flag, set_byte_order.

The following fields of nim affect how the output appears:

  • nifti_type = 0 ==> ANALYZE-7.5 format file pair will be written
  • nifti_type = 1 ==> NIFTI-1 format single file will be written (data offset will be 352+extensions)
  • nifti_type = 2 ==> NIFTI_1 format file pair will be written
  • nifti_type = 3 ==> NIFTI_1 ASCII single file will be written
  • fname is the name of the output file (header or header+data)
  • if a file pair is being written, iname is the name of the data file
  • existing files WILL be overwritten with extreme prejudice
  • if qform_code > 0, the quatern_*, qoffset_*, and qfac fields determine the qform output, NOT the qto_xyz matrix; if you want to compute these fields from the qto_xyz matrix, you can use the utility function nifti_mat44_to_quatern()
See also
nifti_image_write_bricks, nifti_image_free, nifti_set_filenames, nifti_image_write_hdr_img

◆ nifti_image_write_bricks()

void nifti_image_write_bricks ( nifti_image nim,
const nifti_brick_list NBL 
)

similar to nifti_image_write, but data is in NBL struct, not nim->data

See also
nifti_image_write, nifti_image_free, nifti_set_filenames, nifti_free_NBL

◆ nifti_image_write_hdr_img()

znzFile nifti_image_write_hdr_img ( nifti_image nim,
int  write_data,
const char *  opts 
)

write the nifti_image dataset to disk, optionally including data

This is just a front-end for nifti_image_write_hdr_img2.

Parameters
nimnifti_image to write to disk
write_datawrite options (see nifti_image_write_hdr_img2)
optsfile open options ("wb" from nifti_image_write)
See also
nifti_image_write, nifti_image_write_hdr_img2, nifti_image_free, nifti_set_filenames

◆ nifti_image_write_hdr_img2()

znzFile nifti_image_write_hdr_img2 ( nifti_image nim,
int  write_opts,
const char *  opts,
znzFile  imgfile,
const nifti_brick_list NBL 
)

This writes the header (and optionally the image data) to file

If the image data file is left open it returns a valid znzFile handle. It also uses imgfile as the open image file is not null, and modifies it inside.

Parameters
nimnifti_image to write to disk
write_optsflags whether to write data and/or close file (see below)
optsfile-open options, probably "wb" from nifti_image_write()
imgfileoptional open znzFile struct, for writing image data (may be NULL)
NBLoptional nifti_brick_list, containing the image data (may be NULL)

Values for write_opts mode are based on two binary flags ( 0/1 for no-write/write data, and 0/2 for close/leave-open files ) :

  • 0 = do not write data and close (do not open data file)
  • 1 = write data and close
  • 2 = do not write data and leave data file open
  • 3 = write data and leave data file open
See also
nifti_image_write, nifti_image_write_hdr_img, nifti_image_free, nifti_set_filenames

◆ nifti_intent_string()

char const* nifti_intent_string ( int  ii)

Return a pointer to a string holding the name of a NIFTI intent type.

Parameters
iiNIfTI-1 intent code
Returns
pointer to static string describing code
Warning
Do not free() or modify this string! It points to static storage.
See also
NIFTI1_INTENT_CODES group in nifti1.h

◆ nifti_is_complete_filename()

int nifti_is_complete_filename ( const char *  fname)

return whether the filename is valid

Note: uppercase extensions are now valid. 27 Apr 2009 [rickr]

The name is considered valid if the file basename has length greater than zero, AND one of the valid nifti extensions is provided.

fname input | return |

"myimage" | 0 | "myimage.tif" | 0 | "myimage.tif.gz" | 0 | "myimage.nii" | 1 | ".nii" | 0 | ".myhiddenimage" | 0 | ".myhiddenimage.nii" | 1 |

◆ nifti_is_gzfile()

int nifti_is_gzfile ( const char *  fname)

return whether the filename ends in ".gz"

◆ nifti_is_inttype()

int nifti_is_inttype ( int  dt)

Determine if the datatype code dt is an integer type (1=YES, 0=NO).

Returns
whether the given NIfTI-1 datatype code is valid
See also
NIFTI1_DATATYPES group in nifti1.h

◆ nifti_is_valid_datatype()

int nifti_is_valid_datatype ( int  dtype)

check whether the given type is on the "approved" list

The type is explicitly checked against the NIFTI_TYPE_* list in nifti1.h.

Returns
1 if dtype is valid, 0 otherwise
See also
NIFTI_TYPE_* codes in nifti1.h

◆ nifti_is_valid_ecode()

int nifti_is_valid_ecode ( int  ecode)

check whether the extension code is valid

Returns
1 if valid, 0 otherwise

◆ nifti_make_new_header()

nifti_1_header* nifti_make_new_header ( const int  arg_dims[],
int  arg_dtype 
)

basic initialization of a nifti_1_header struct (with given dimensions)

Return an allocated nifti_1_header struct, based on the given dimensions and datatype.

Parameters
arg_dims: optional dim[8] array (default {3,1,1,1,0,0,0,0})
arg_dtype: optional datatype (default DT_FLOAT32)
Returns
pointer to allocated nifti_1_header struct

◆ nifti_make_new_nim()

nifti_image* nifti_make_new_nim ( const int  dims[],
int  datatype,
int  data_fill 
)

basic creation of a nifti_image struct

Create a nifti_image from the given dimensions and data type. Optinally, allocate zero-filled data.

Parameters
dims: optional dim[8] (default {3,1,1,1,0,0,0,0})
datatype: optional datatype (default DT_FLOAT32)
data_fill: if flag is set, allocate zero-filled data for image
Returns
pointer to allocated nifti_image struct

◆ nifti_make_orthog_mat44()

mat44 nifti_make_orthog_mat44 ( float  r11,
float  r12,
float  r13,
float  r21,
float  r22,
float  r23,
float  r31,
float  r32,
float  r33 
)

Input 9 floats and make an orthgonal mat44 out of them.

Each row is normalized, then nifti_mat33_polar() is used to orthogonalize them. If row #3 (r31,r32,r33) is input as zero, then it will be taken to be the cross product of rows #1 and #2.

This function can be used to create a rotation matrix for transforming an oblique volume to anatomical coordinates. For this application:

  • row #1 (r11,r12,r13) is the direction vector along the image i-axis
  • row #2 (r21,r22,r23) is the direction vector along the image j-axis
  • row #3 (r31,r32,r33) is the direction vector along the slice direction (if available; otherwise enter it as 0's)

The first 2 rows can be taken from the DICOM attribute (0020,0037) "Image Orientation (Patient)".

After forming the rotation matrix, the complete affine transformation from (i,j,k) grid indexes to (x,y,z) spatial coordinates can be computed by multiplying each column by the appropriate grid spacing:

  • column #1 (R.m[0][0],R.m[1][0],R.m[2][0]) by delta-x
  • column #2 (R.m[0][1],R.m[1][1],R.m[2][1]) by delta-y
  • column #3 (R.m[0][2],R.m[1][2],R.m[2][2]) by delta-z

and by then placing the center (x,y,z) coordinates of voxel (0,0,0) into the column #4 (R.m[0][3],R.m[1][3],R.m[2][3]).

See also
nifti_quatern_to_mat44, nifti_mat44_to_quatern, nifti_mat44_to_orientation

◆ nifti_makebasename()

char* nifti_makebasename ( const char *  fname)

duplicate the filename, while clearing any extension

This allocates memory for basename which should eventually be freed.

◆ nifti_makehdrname()

char* nifti_makehdrname ( const char *  prefix,
int  nifti_type,
int  check,
int  comp 
)

creates a filename for storing the header, based on nifti_type

Parameters
prefix- this will be copied before the suffix is added
nifti_type- determines the extension, unless one is in prefix
check- check for existence (fail condition)
comp- add .gz for compressed name

Note that if prefix provides a file suffix, nifti_type is not used.

NB: this allocates memory which should be freed

See also
nifti_set_filenames

◆ nifti_makeimgname()

char* nifti_makeimgname ( const char *  prefix,
int  nifti_type,
int  check,
int  comp 
)

creates a filename for storing the image, based on nifti_type

Parameters
prefix- this will be copied before the suffix is added
nifti_type- determines the extension, unless provided by prefix
check- check for existence (fail condition)
comp- add .gz for compressed name

Note that if prefix provides a file suffix, nifti_type is not used.

NB: it allocates memory which should be freed

See also
nifti_set_filenames

◆ nifti_mat33_colnorm()

float nifti_mat33_colnorm ( mat33  A)

compute the max column norm of a 3x3 matrix

◆ nifti_mat33_determ()

float nifti_mat33_determ ( mat33  R)

compute the determinant of a 3x3 matrix

◆ nifti_mat33_inverse()

mat33 nifti_mat33_inverse ( mat33  R)

compute the inverse of a 3x3 matrix

◆ nifti_mat33_mul()

mat33 nifti_mat33_mul ( mat33  A,
mat33  B 
)

multiply 2 3x3 matrices

◆ nifti_mat33_polar()

mat33 nifti_mat33_polar ( mat33  A)

polar decomposition of a 3x3 matrix

This finds the closest orthogonal matrix to input A (in both the Frobenius and L2 norms).

Algorithm is that from NJ Higham, SIAM J Sci Stat Comput, 7:1160-1174.

◆ nifti_mat33_rownorm()

float nifti_mat33_rownorm ( mat33  A)

compute the max row norm of a 3x3 matrix

◆ nifti_mat44_inverse()

mat44 nifti_mat44_inverse ( mat44  R)

Compute the inverse of a bordered 4x4 matrix.

  • Some numerical code fragments were generated by Maple 8.
  • If a singular matrix is input, the output matrix will be all zero.
  • You can check for this by examining the [3][3] element, which will be 1.0 for the normal case and 0.0 for the bad case.

    The input matrix should have the form: [ r11 r12 r13 v1 ] [ r21 r22 r23 v2 ] [ r31 r32 r33 v3 ] [ 0 0 0 1 ]

◆ nifti_mat44_to_orientation()

void nifti_mat44_to_orientation ( mat44  R,
int *  icod,
int *  jcod,
int *  kcod 
)

compute the (closest) orientation from a 4x4 ijk->xyz tranformation matrix

Input:  4x4 matrix that transforms (i,j,k) indexes to (x,y,z) coordinates,
        where +x=Right, +y=Anterior, +z=Superior.
        (Only the upper-left 3x3 corner of R is used herein.)
Output: 3 orientation codes that correspond to the closest "standard"
        anatomical orientation of the (i,j,k) axes.
Method: Find which permutation of (x,y,z) has the smallest angle to the
        (i,j,k) axes directions, which are the columns of the R matrix.
Errors: The codes returned will be zero.
For example, an axial volume might get return values of
  *icod = NIFTI_R2L   (i axis is mostly Right to Left)
  *jcod = NIFTI_P2A   (j axis is mostly Posterior to Anterior)
  *kcod = NIFTI_I2S   (k axis is mostly Inferior to Superior)
See also
"QUATERNION REPRESENTATION OF ROTATION MATRIX" in nifti1.h
nifti_quatern_to_mat44, nifti_mat44_to_quatern, nifti_make_orthog_mat44

◆ nifti_mat44_to_quatern()

void nifti_mat44_to_quatern ( mat44  R,
float *  qb,
float *  qc,
float *  qd,
float *  qx,
float *  qy,
float *  qz,
float *  dx,
float *  dy,
float *  dz,
float *  qfac 
)

Given the 3x4 upper corner of the matrix R, compute the quaternion parameters that fit it.

  • Any NULL pointer on input won't get assigned (e.g., if you don't want dx,dy,dz, just pass NULL in for those pointers).
  • If the 3 input matrix columns are NOT orthogonal, they will be orthogonalized prior to calculating the parameters, using the polar decomposition to find the orthogonal matrix closest to the column-normalized input matrix.
  • However, if the 3 input matrix columns are NOT orthogonal, then the matrix produced by nifti_quatern_to_mat44 WILL have orthogonal columns, so it won't be the same as the matrix input here. This "feature" is because the NIFTI 'qform' transform is deliberately not fully general – it is intended to model a volume with perpendicular axes.
  • If the 3 input matrix columns are not even linearly independent, you'll just have to take your luck, won't you?
See also
"QUATERNION REPRESENTATION OF ROTATION MATRIX" in nifti1.h
nifti_quatern_to_mat44, nifti_make_orthog_mat44, nifti_mat44_to_orientation

◆ nifti_nim_has_valid_dims()

int nifti_nim_has_valid_dims ( nifti_image nim,
int  complain 
)

validate nifti dimensions

Returns
1 if valid, 0 if not
See also
nifti_nim_is_valid, nifti_hdr_looks_good

rely on dim[] as the master

  • start with dim[0]: failure here is considered terminal
  • check whether ndim equals dim[0]
  • compare each dim[i] to the proper nx, ny, ...
  • check the dimensions, and that their product matches nvox
  • if debug, warn about any remaining dim that is neither 0, nor 1
  • return invalid or valid

◆ nifti_nim_is_valid()

int nifti_nim_is_valid ( nifti_image nim,
int  complain 
)

validate the nifti_image

Returns
1 if the structure seems valid, otherwise 0
See also
nifti_nim_has_valid_dims, nifti_hdr_looks_good
  • check that dim[] matches the individual values ndim, nx, ny, ...
  • be explicit in return of 0 or 1

◆ nifti_orientation_string()

char const* nifti_orientation_string ( int  ii)

Return a pointer to a string holding the name of a NIFTI orientation.

Parameters
iiorientation code
Returns
pointer to static string holding the orientation information
Warning
Do not free() or modify the return string! It points to static storage.
See also
NIFTI_L2R in nifti1_io.h

◆ nifti_quatern_to_mat44()

mat44 nifti_quatern_to_mat44 ( float  qb,
float  qc,
float  qd,
float  qx,
float  qy,
float  qz,
float  dx,
float  dy,
float  dz,
float  qfac 
)

Given the quaternion parameters (etc.), compute a transformation matrix.

See comments in nifti1.h for details.

  • qb,qc,qd = quaternion parameters
  • qx,qy,qz = offset parameters
  • dx,dy,dz = grid stepsizes (non-negative inputs are set to 1.0)
  • qfac = sign of dz step (< 0 is negative; >= 0 is positive)
If qx=qy=qz=0, dx=dy=dz=1, then the output is a rotation matrix.
For qfac >= 0, the rotation is proper.
For qfac <  0, the rotation is improper.
See also
"QUATERNION REPRESENTATION OF ROTATION MATRIX" in nifti1.h
nifti_mat44_to_quatern, nifti_make_orthog_mat44, nifti_mat44_to_orientation

◆ nifti_read_ascii_image()

nifti_image* nifti_read_ascii_image ( znzFile  fp,
char *  fname,
int  flen,
int  read_data 
)

nifti_read_ascii_image - process as a type-3 .nia image file

return NULL on failure

NOTE: this is NOT part of the NIFTI-1 standard

◆ nifti_read_buffer()

size_t nifti_read_buffer ( znzFile  fp,
void *  dataptr,
size_t  ntot,
nifti_image nim 
)

read ntot bytes of data from an open file and byte swaps if necessary

note that nifti_image is required for information on datatype, bsize (for any needed byte swapping), etc.

This function does not allocate memory, so dataptr must be valid.

◆ nifti_read_collapsed_image()

int nifti_read_collapsed_image ( nifti_image nim,
const int  dims[8],
void **  data 
)

read a nifti image, collapsed across dimensions according to dims[8]

This function may be used to read parts of a nifti dataset, such as
the time series for a single voxel, or perhaps a slice.  It is similar
to nifti_image_load(), though the passed 'data' parameter is used for
returning the image, not nim->data.
Parameters
nimgiven nifti_image struct, corresponding to the data file
dimsgiven list of dimensions (see below)
datapointer to data pointer (if *data is NULL, data will be allocated, otherwise not)
Here, dims is an array of 8 ints, similar to nim->dim[8]. While dims[0] is unused at this point, the other indices specify which dimensions to collapse (and at which index), and which not to collapse. If dims[i] is set to -1, then that entire dimension will be read in, from index 0 to index (nim->dim[i] - 1). If dims[i] >= 0, then only that index will be read in (so dims[i] must also be < nim->dim[i]).
Example: given  nim->dim[8] = { 4, 64, 64, 21, 80, 1, 1, 1 } (4-D dataset)
  if dims[8] = { 0,  5,  4, 17, -1, -1, -1, -1 }
     -> read time series for voxel i,j,k = 5,4,17
  if dims[8] = { 0, -1, -1, -1, 17, -1, -1, -1 }
     -> read single volume at time point 17
Example: given  nim->dim[8] = { 6, 64, 64, 21, 80, 4, 3, 1 } (6-D dataset)
  if dims[8] = { 0, 5, 4, 17, -1, 2, 1, 0 }
     -> read time series for the voxel i,j,k = 5,4,17, and dim 5,6 = 2,1
  if dims[8] = { 0, 5, 4, -1, -1, 0, 0, 0 }
     -> read time series for slice at i,j = 5,4, and dim 5,6,7 = 0,0,0
        (note that dims[7] is not relevant, but must be 0 or -1)
If *data is NULL, then *data will be set as a pointer to new memory,
allocated here for the resulting collapsed image data.
  e.g. { int    dims[8] = { 0,  5,  4, 17, -1, -1, -1, -1 };
         void * data    = NULL;
         ret_val = nifti_read_collapsed_image(nim, dims, &data);
         if( ret_val > 0 ){
            process_time_series(data);
            if( data != NULL ) free(data);
         }
       }
NOTE: If *data is not NULL, then it will be assumed that it points to
      valid memory, sufficient to hold the results.  This is done for
      speed and possibly repeated calls to this function.
  e.g. { int    dims[8] = { 0,  -1, -1, -1, -1, -1, -1, -1 };
         void * data    = NULL;
         for( zslice = 0; zslice < nzslices; zslice++ ){
            dims[3] = zslice;
            ret_val = nifti_read_collapsed_image(nim, dims, &data);
            if( ret_val > 0 ) process_slice(zslice, data);
         }
         if( data != NULL ) free(data);
       }
Returns
  • the total number of bytes read, or < 0 on failure
  • the read and byte-swapped data, in 'data'
See also
nifti_image_read, nifti_image_free, nifti_image_read_bricks nifti_image_load
  • check pointers for sanity
  • verify that dim[] makes sense
  • verify that dims[] makes sense for this dataset
  • prepare pivot list - pivots are fixed indices
  • open the image file for reading at the appropriate offset
  • call the recursive reading function, passing nim, the pivot info, location to store memory, and file pointer and position

◆ nifti_read_header()

nifti_1_header* nifti_read_header ( const char *  hname,
int *  swapped,
int  check 
)

return an allocated and filled nifti_1_header struct

Read the binary header from disk, and swap bytes if necessary.

Returns
an allocated nifti_1_header struct, or NULL on failure
Parameters
hnamename of file containing header
swappedif not NULL, return whether header bytes were swapped
checkflag to check for invalid nifti_1_header
Warning
ASCII header type is not supported
See also
nifti_image_read, nifti_image_free, nifti_image_read_bricks

◆ nifti_read_subregion_image()

int nifti_read_subregion_image ( nifti_image nim,
int *  start_index,
int *  region_size,
void **  data 
)

read an arbitrary subregion from a nifti image

This function may be used to read a single arbitary subregion of any rectangular size from a nifti dataset, such as a small 5x5x5 subregion around the center of a 3D image.

Parameters
nimgiven nifti_image struct, corresponding to the data file
start_indexthe index location of the first voxel that will be returned
region_sizethe size of the subregion to be returned
datapointer to data pointer (if *data is NULL, data will be allocated, otherwise not)

Example: given nim->dim[8] = {3, 64, 64, 64, 1, 1, 1, 1 } (3-D dataset)

if start_index[7] = { 29, 29, 29, 0, 0, 0, 0 } and region_size[7] = { 5, 5, 5, 1, 1, 1, 1 } -> read 5x5x5 region starting with the first voxel location at (29,29,29)

NOTE: If *data is not NULL, then it will be assumed that it points to valid memory, sufficient to hold the results. This is done for speed and possibly repeated calls to this function.

Returns
  • the total number of bytes read, or < 0 on failure
  • the read and byte-swapped data, in 'data'
See also
nifti_image_read, nifti_image_free, nifti_image_read_bricks nifti_image_load, nifti_read_collapsed_image

◆ nifti_set_allow_upper_fext()

void nifti_set_allow_upper_fext ( int  allow)

set nifti's global allow_upper_fext flag 28 Apr 2009 [rickr]

explicitly set to 0 or 1

◆ nifti_set_debug_level()

void nifti_set_debug_level ( int  level)

set nifti's global debug level, for status reporting

  • 0 : quiet, nothing is printed to the terminal, but errors
  • 1 : normal execution (the default)
  • 2, 3 : more details

◆ nifti_set_filenames()

int nifti_set_filenames ( nifti_image nim,
const char *  prefix,
int  check,
int  set_byte_order 
)

create and set new filenames, based on prefix and image type

Parameters
nimpointer to nifti_image in which to set filenames
prefix(required) prefix for output filenames
checkcheck for previous existence of filename (existence is an error condition)
set_byte_orderflag to set nim->byteorder here (this is probably a logical place to do so)
Returns
0 on successful update
Warning
this will free() any existing names and create new ones
See also
nifti_makeimgname, nifti_makehdrname, nifti_type_and_names_match

◆ nifti_set_iname_offset()

void nifti_set_iname_offset ( nifti_image nim)

set the nifti_image iname_offset field, based on nifti_type

  • if writing to 2 files, set offset to 0
  • if writing to a single NIFTI-1 file, set the offset to 352 + total extension size, then align to 16-byte boundary
  • if writing an ASCII header, set offset to -1

◆ nifti_set_skip_blank_ext()

void nifti_set_skip_blank_ext ( int  skip)

set nifti's global skip_blank_ext flag 5 Sep 2006 [rickr]

explicitly set to 0 or 1

◆ nifti_set_type_from_names()

int nifti_set_type_from_names ( nifti_image nim)

set the nifti_type field based on fname and iname

Note that nifti_type is changed only when it does not match the filenames.

Returns
0 on success, -1 on error
See also
is_valid_nifti_type, nifti_type_and_names_match

◆ nifti_short_order()

int nifti_short_order ( void  )

get the byte order for this CPU

  • LSB_FIRST means least significant byte, first (little endian)
  • MSB_FIRST means most significant byte, first (big endian)

◆ nifti_simple_init_nim()

nifti_image* nifti_simple_init_nim ( void  )

basic initialization of a nifti_image struct (to a 1x1x1 image)

◆ nifti_slice_string()

char const* nifti_slice_string ( int  ss)

Return a pointer to a string holding the name of a NIFTI slice_code.

Parameters
ssNIfTI-1 slice order code
Returns
pointer to static string describing code
Warning
Do not free() or modify this string! It points to static storage.
See also
NIFTI1_SLICE_ORDER group in nifti1.h

◆ nifti_strdup()

char* nifti_strdup ( const char *  str)

duplicate the given string (alloc length+1)

Returns
allocated pointer (or NULL on failure)

◆ nifti_swap_16bytes()

void nifti_swap_16bytes ( size_t  n,
void *  ar 
)

swap 16 bytes at a time from the given list of n sets of 16 bytes

◆ nifti_swap_2bytes()

void nifti_swap_2bytes ( size_t  n,
void *  ar 
)

swap each byte pair from the given list of n pairs

Due to alignment of structures at some architectures (e.g. on ARM), stick to char varaibles. Fixes http://bugs.debian.org/446893 Yaroslav debia.nosp@m.n@on.nosp@m.eruss.nosp@m.ian..nosp@m.com

◆ nifti_swap_4bytes()

void nifti_swap_4bytes ( size_t  n,
void *  ar 
)

swap 4 bytes at a time from the given list of n sets of 4 bytes

◆ nifti_swap_8bytes()

void nifti_swap_8bytes ( size_t  n,
void *  ar 
)

swap 8 bytes at a time from the given list of n sets of 8 bytes

perhaps use this style for the general Nbytes, as Yaroslav suggests

◆ nifti_swap_as_analyze()

int nifti_swap_as_analyze ( nifti_analyze75 h)

Byte swap as an ANALYZE 7.5 header

return non-zero on failure

◆ nifti_swap_Nbytes()

void nifti_swap_Nbytes ( size_t  n,
int  siz,
void *  ar 
)

based on siz, call the appropriate nifti_swap_Nbytes() function

◆ nifti_test_datatype_sizes()

int nifti_test_datatype_sizes ( int  verb)

Only as a test, verify that the new nifti_type_list table matches the the usage of nifti_datatype_sizes (which could be changed to use the table, if there were interest).

return the number of errors (so 0 is success, as usual)

◆ nifti_type_and_names_match()

int nifti_type_and_names_match ( nifti_image nim,
int  show_warn 
)

check whether nifti_type matches fname and iname for the nifti_image

  • if type 0 or 2, expect .hdr/.img pair
  • if type 1, expect .nii (and names must match)
Parameters
nimgiven nifti_image
show_warnif set, print a warning message for any mis-match
Returns
  • 1 if the values seem to match
  • 0 if there is a mis-match
  • -1 if there is not sufficient information to create file(s)
See also
NIFTI_FTYPE_* codes in nifti1_io.h
nifti_set_type_from_names, is_valid_nifti_type

◆ nifti_units_string()

char const* nifti_units_string ( int  uu)

Return a pointer to a string holding the name of a NIFTI units type.

Parameters
uuNIfTI-1 unit code
Returns
pointer to static string for the given unit type
Warning
Do not free() or modify this string! It points to static storage.
See also
NIFTI1_UNITS group in nifti1.h

◆ nifti_update_dims_from_array()

int nifti_update_dims_from_array ( nifti_image nim)

nifti_update_dims_from_array - update nx, ny, ... from nim->dim[]

Fix all the dimension information, based on a new nim->dim[].

Note: we assume that dim[0] will not increase.

Check for updates to pixdim[], dx,..., nx,..., nvox, ndim, dim[0].

◆ nifti_validfilename()

int nifti_validfilename ( const char *  fname)

return whether the filename is valid

Allow uppercase extensions as valid. 27 Apr 2009 [rickr] Any .gz extension case must match the base extension case.

The name is considered valid if its length is positive, excluding any nifti filename extension.

fname input | return | result of nifti_makebasename

"myimage" | 1 | "myimage" "myimage.tif" | 1 | "myimage.tif" "myimage.tif.gz" | 1 | "myimage.tif" "myimage.nii" | 1 | "myimage" ".nii" | 0 | <ERROR - basename has zero length> ".myhiddenimage" | 1 | ".myhiddenimage" ".myhiddenimage.nii | 1 | ".myhiddenimage"

◆ nifti_write_all_data()

int nifti_write_all_data ( znzFile  fp,
nifti_image nim,
const nifti_brick_list NBL 
)

write the nifti_image data to file (from nim->data or from NBL)

If NBL is not NULL, write the data from that structure. Otherwise, write it out from nim->data. No swapping is done here.

Parameters
fp: File pointer
nim: nifti_image corresponding to the data
NBL: optional source of write data (if NULL use nim->data)
Returns
0 on success, -1 on failure

Note: the nifti_image byte_order is set as that of the current CPU. This is because such a conversion was made to the data upon reading, while byte_order was not set (so the programs would know what format the data was on disk). Effectively, since byte_order should match what is on disk, it should bet set to that of the current CPU whenever new filenames are assigned.

◆ nifti_write_ascii_image()

znzFile nifti_write_ascii_image ( nifti_image nim,
const nifti_brick_list NBL,
const char *  opts,
int  write_data,
int  leave_open 
)

write a nifti_image to disk in ASCII format

◆ nifti_xform_string()

char const* nifti_xform_string ( int  xx)

Return a pointer to a string holding the name of a NIFTI transform type.

Parameters
xxNIfTI-1 xform code
Returns
pointer to static string describing xform code
Warning
Do not free() or modify this string! It points to static storage.
See also
NIFTI1_XFORM_CODES group in nifti1.h

◆ old_swap_nifti_header()

void old_swap_nifti_header ( struct nifti_1_header h,
int  is_nifti 
)

OLD VERSION of swap_nifti_header (left for undo/compare operations)

Byte swap NIFTI-1 file header in various places and ways.

If is_nifti is nonzero, will also swap the NIFTI-specific components of the header; otherwise, only the components common to NIFTI and ANALYZE will be swapped.

◆ swap_nifti_header()

void swap_nifti_header ( struct nifti_1_header h,
int  is_nifti 
)

Byte swap NIFTI-1 file header in various places and ways.

If is_nifti, swap all (even UNUSED) fields of NIfTI header. Else, swap as a nifti_analyze75 struct.

◆ valid_nifti_brick_list()

int valid_nifti_brick_list ( nifti_image nim,
int  nbricks,
const int *  blist,
int  disp_error 
)

valid_nifti_brick_list - check sub-brick list for image

This function verifies that nbricks and blist are appropriate for use with this nim, based on the dimensions.

Parameters
nimnifti_image to check against
nbricksnumber of brick indices in blist
blistlist of brick indices to check in nim
disp_errorif this flag is set, report errors to user
Returns
1 if valid, 0 if not

◆ valid_nifti_extensions()

int valid_nifti_extensions ( const nifti_image nim)

for each extension, check code, size and data pointer