nx2img
======

Synopsis
--------

.. code-block:: bash
    
    nx2img [OPTIONS] [NEXUS PATH]

Description
-----------

``nx2img`` is a command line program implemented as a Python3 script which
converts image data stored in a NeXus file into individual image files. 
The currently supported image formats are ``TIFF`` and ``CBF``. 
``nx2img`` takes the NeXus path to a data field holding the image data as its
only argument. The way how the data will be distributed to the individual image
files depends on the rank (number of dimensions) of the input field 

* if the field has a rank of 2 the entire field is considered a single image
  and written as such to disk
* if the field has a rank of 3 the first dimension represents the image index 
  while the remaining two dimensions represent the x- and y-dimension of the 
  image. 

If, instead of a full NeXus path, only the file name is given the program
assumes the default path to ``/:NXentry/:NXinstrument/:NXdetector/data``.

Options
-------

-h, --help            show a brief program help and terminate the program
-f, --output-format   image format to use for the files (default is TIFF)
-p, --output-path     path to the directory where to write the data, the 
                      default is the current working directory
-s, --start-index     the starting index of the images (default=0)
-t, --file-template   the file template used to generate the image file names,
                      the default value is ``img_%05i.tiff``


Examples
--------

The most simplest call to ``nx2img`` looks like 

.. code-block:: bash

    $ nx2img data.nxs://:NXentry/:NXinstrument/:NXdetector/data

which would result in 

.. code-block:: bash

    $ ls 
      img_00000.tiff
      img_00001.tiff
      img_00002.tiff

a bunch of TIFF files in the current working directory. To change the file
names and the numbering scheme one could use something like this 

.. code-block:: bash

    $ nx2img -fcbf -tdata_%i.cbf data.nxs://:NXentry/:NXinstrument/:NXdetector/data

which will result into 

.. code-block:: bash

    $ ls 
      data_0.cbf
      data_1.cbf
      data_3.cbf


Return value
------------

Returns 0 in case of success and 1 in case of errors.