Extract Nexus data : nxextractor


for other NeXus tools and utilities, see : http://www.nexusformat.org/



Just type 'nxextractor"' in a console. You will get the usage string as output:


$ nxextractor

INFO app:Found default configuration file: /usr/Local/configFiles/GD/RecordingConfigurations/common/nxextract.conf
ERROR app:No template file provided!!
nxextractor v1.16.0
nxextract options input NeXus Files and/or directories...
-t, --template <file>                  Template file
-D, --Define <symbols>                 Symbols list
-l, --list                             Templates list
-c, --configuration <file>             Configuration file
-s, --silent                           Silent mode
-m, --mode <octal value>               Access mode of output files in octal ex:'755'
-w, --ownership <user_id:group_id>     User and group in the form 'user:group'
-h, --help                             Show this usage
-v, --version                          Program version

The line show us the tool has found the file 'nxextract.conf'. This file contains configuration parameters of the tool and should be edited by power users only, it content is explained in a dedicated page.



nxextractor is invoked using a template which describe the expected extraction/output. A output consist of one or several ASCII or binary files.

There are two ways of choosing a template:

  • by it's full path:

    nxextractor -t /path/to/my/template.nxs ...

  • by it's name, which is a shortest way:

    nxextractor -t template ...

The second method uses the configuration file (nxextract.conf) to find the template trough a set of directory paths. If the template is not found by this method, you should use the first.


To retreive the list of available templates (through the configuration file nxextract.conf), use the --list option alone, like in this example:
$ nxextractor --list
INFO app:Found default configuration file: /usr/Local/configFiles/GD/RecordingConfigurations/common/nxextract.conf

The --list option has returned two names: scan_1D_images_bmp_raw and scan. On this server one can use the short way to invoke these templates.


This option allow the declaration of a symbol and a associated value. This symbol value is used by the template. Thus, its usage depends of the template.
By convention, the symbol dir is used in all the templates: it define the output directory path:
$nxextractor -t my_template -D dir=/output/path ...
NOTE: Do not forget the space between --Define (or -D) and the name of the symbol !

However, the usage of this option and the dir symbol is not mandatory. This is the case (at SOLEIL) if the configuration file nxextract.conf contains a set of rules defining the right output path into the storage facility according to the location of the input nexus files.


Allow the user to manually provide the full path of a configuration file to use:
$nxextractor -c /path/to/my/configuration/file ...


Turn-off thelog messages (warning, info)

mode & ownership

These options are available only when running nxextractor on linux systems under 'root' account. It allows to automatically sets the rights and ownership of extracted files.

An example: How to extract data from NeXus files stored a project directory

This example are working on every SOLEIL beamlines.
In order to be able to get read access on data fro the project 'm_project' you have to log as user 'my_project' on a terminal in the beamline control network:

srv2$ su - 'my_project'

Lets suppose the data were acquired using the ScanServer, so the template to use is 'scan'.
Running the extracting tool in order to extract data from all NeXus files stored in a directory:

$nxextractor -t scan /nfs/ruche-{beamline}/{beamline}-users/my_project/{NeXus files directory}/