img2nx
======

Synopsis
--------
Moves data from individual image files to a singel image stack in a 
NeXus file.

.. code-block:: bash
    
    img2nx [OPTIONS] [DETECTOR FILES]

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

``img2nx`` stores the data stored in an individual image files to an image 
stack within a NeXus file. The program assues that the group where the data 
should be stored exists (you have to create a basic NeXus-file first). 
However, concerning the data field two modes of operation can be 
distinguished 

* the datafield in the target path exists: in this case the program 
  checks if the first image the user wants to append fits into the 
  stack and aborts if this is not the case 
* the data-field does not exist: in this case a new field will be 
  created which can store the data from the first image in the 
  stack provided by the user.   
  
The detector files can be provided either by individually listing 
them as command line arguments to ``img2nx`` or by using the special 
syntax based on C format strings. 
Consider the following series of image files 

.. code-block:: bash 

   $ls 
   img_0001.tif
   img_0002.tif
   img_0003.tif
   .
   .
   .
   img_1000.tif
   
These files could be addressed using a syntax like this 
``img_%04i.tif:1:1000``. 

``img2nx`` provides extensive logging information which, in case of an 
unexpected program termination, can be used to continue a run to finish the 
original job. 

Options
-------

-h, --help         show a brief overview on program useage and options
-t, --target       the NeXus path to the field where the data should be stored
-d, --deflate      if set to a value between 1 and 9 deflate compression will 
                   be used on a newly created dataset. Obviously this only 
                   works if the dataset is created by `img2nx`.
-d, --log-file     a file where all the log messages from the program will 
                   be stored. In addition to this output will also be 
                   written to standard error
-q, --quiet        no output to standard error. This is particularly usefull 
                   when `img2nx` is used along with the ``-l`` option where 
                   the logging output is anyhow written to a file on disk.

Examples
--------

In the first case we have a bunch of TIF images which should be stored 
in the stack

.. code-block:: bash

   $ls 
   img_0001.tif
   img_0002.tif
   img_0003.tif
   .
   .
   .
   img_1000.tif
   
To store them in the detector group of a NeXus file we can use 

.. code-block:: bash

   $img2nx -tdata.nx://:NXentry/:NXinstrument/:NXdetector/data img_%04i.tif:1:1000
   
If the field ``data`` in the detector group of the file already exists 
the data from the image files will be appended, if the field does not exist
it will be created according to the data stored in the first image.

If we want to do the same job for instance for a batch queue we rather want no
logging output on the command line but rather store this information into 
a file. This can be achieved with

.. code-block:: bash 

   $TARGET_PATH=data.nx://:NXentry/:NXinstrument/:NXdetector/data
   $img2nx -q -lsample.log -t$TARGET_PATH img_%04i.tif:1:1000

The ``-q`` option stops logging information to be propagated to the 
standard error channel of the console while the ``-l`` option determines
the file where the logging information shall be stored. 

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

The program returns 0 in the case of success, 1 otherwise.