.. -*- mode: rst -*-
.. ex: set sts=4 ts=4 sw=4 et tw=79:
  ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ###
  #
  #   See COPYING file distributed along with the NiBabel package for the
  #   copyright and license terms.
  #
  ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ###

.. _intro:

***************************
What do I need NiBabel for?
***************************

NiBabel_ is a python package for reading and writing medical image
formats.  At the moment it has fairly full support of Analyze_ and
Nifti_ images, and read support for MINC_ images.

NiBabel and PyNifti
===================

We designed NiBabel_ to replace PyNifti_.  PyNifti_ is a Python package
that wraps the Nifti_ C implementation - nifticlibs_ .  Although
NiBabel_ has much of the same functionality, it has a different
interface, and does not use the Nifti_ C libraries.

NIfTI
=====

NIfTI_ is a new Analyze-style data format, proposed by the `NIfTI Data Format
Working Group`_ as a *"short-term measure to facilitate inter-operation of
functional MRI data analysis software packages"*. Meanwhile a number of
toolkits are NIfTI-aware (e.g. FSL, AFNI, SPM, Freesurfer and a to a certain
degree also Brainvoyager). Additionally, dicomnifti_ allows the direct
conversion from DICOM images into the NIfTI format.

We don't use it in ``nibabel``, but libnifti_ provides a reference
implementation of a C library to read, write and manipulate NIfTI
images. The library source code is put into the public domain and a
corresponding project is hosted at the `libnifti Sourceforge`_ site.

In addition to the C library, there is also an IO library written in Java and
Matlab functions to make use of NIfTI files from within Matlab.

.. _NIfTI: http://nifti.nimh.nih.gov
.. _NIfTI Data Format Working Group: http://nifti.nimh.nih.gov/dfwg/beyond-nifti-1
.. _dicomnifti: http://cbi.nyu.edu/software/dinifti.php
.. _libnifti: http://niftilib.sf.net/niftilib_overview.html
.. _libnifti SourceForge: http://sourceforge.net/projects/niftilib


Python
======

Python has a large number of easy-to-use, high-quality libraries for
signal processing available for Python (e.g.  SciPy).

Moreover Python has bindings to almost any important language/program in the
fields of maths, statistics and/or engineering. If you want to use R_ to
calculate some stats in a Python script, simply use RPy_ and pass any data
to R. If you don't care about R, but Matlab is your one and only friend, there
are at least two different Python modules to control Matlab from within Python
scripts. Python is the glue between all those helpers and the Python user is
able to combine as many tools as necessary to solve a given problem
-- the easiest way.

.. _R: http://www.r-project.org
.. _RPy: http://rpy.sourceforge.net/


NiBabel and NIfTI
=================

NiBabel is not yet complete (i.e. doesn't support everything the
libnifti_ C package does), it already provides access to the most
important features of the NIfTI-1 data format and *libniftiio*
capabilities. The following features are currently implemented:

* NiBabel can read and write a variety of file formats. This includes
  NIfTI (single and pairs) as well as ANALYZE files, both also in
  gzipped versions.

* NiBabel provides fast and convenient access to the image data via NumPy_
  arrays. This should enable users to process image data with most (if not
  all) numerical routines available for Python. The NumPy array automatically
  uses a datatype corresponding to the NIfTI image data -- no unnecessary
  upcasting is performed.

* NiBabel provides full read and write access to the NIfTI header data. Header
  information can be exported to a Python dictionary and can also be updated
  by using information from a dictionary.

* Besides accessing NIfTI data from files, NiBabel is able to create
  NIfTI and other images from NumPy arrays. The appropriate NIfTI header
  information is determined from the array properties. Additional header
  information can be optionally specified -- making it easy to clone
  NIfTI images if necessary, but with minor modifications.

* Most properties of images are accessible via attributes and/or
  accessor functions of the image header (obtained with
  ``img.get_header()``.. Inter-dependent properties are automatically
  updated if necessary (e.g. modifying the Q-Form matrix also updates
  the pixdim properties and quaternion representation).

* All properties are accessible via Python-style datatypes: A 4x4 matrix is
  an array not 16 individual numbers.

* NiBabel should be resonably fast. Image data will only be loaded into
  the memory if necessary. Simply opening an image file to access some
  header data is performed with virtually no delay independent of the
  size of the image.  Unless image resizing or datatype conversion must
  be performed the image data can be shared by the NIfTI image and
  accessing NumPy arrays, and therefore memory won't be wasted memory
  with redundant copies of the image data.

* Additionally NiBabel can access uncompressed NIfTI or ANALYZE files by
  providing memory-mapped access to them via NumPy's memmap arrays. In this
  mode it is possible to modified existing files of any size without having
  to load them in memory first.

* NiBabel allows to embed arbitrary additional information into the NIfTI file
  header.


Scripts
=======

Some functions provided by NiBabel also might be useful outside the Python
environment and it might be useful to export them via some command line scripts.

Known issues
============

NiBabel currently ignores the origin field of ANALYZE files - it is neither
read nor written. A possible workaround is to convert ANALYZE files into the
NIfTI format using FSL's ``fslchfiletype``.


Things to know
==============

When accessing NIfTI image data through NumPy arrays the order of the
dimensions is as implied by the Nifti standard. If the *x, y, z, t*
dimensions of a NIfTI image are 64, 64, 32, 456 (as for example reported
by ``nifti_tool``), the shape of the NumPy array (e.g. as returned by
``img.get_data()``) will be the same - 64, 64, 32, 456.  This is
different from the previous PyNifti_ interface - but the same as - for
example - the behavior of SPM_.  

.. include:: links_names.txt
