New upstream version 0.7.0+dfsg

6 files changed, 207 insertions, 0 deletions

diff --git a/doc/source/applications/convert.rst b/doc/source/applications/convert.rst
new file mode 100644
index 0000000..28da60b
--- /dev/null
+++ b/doc/source/applications/convert.rst
@@ -0,0 +1,130 @@
+
+silx convert
+============
+
+Purpose
+-------
+
+The *silx convert* command is provided to help with archiving legacy file
+formats into HDF5 files.
+
+You can refer to following tutorials for additional information
+about the output format:
+
+ - :doc:`../Tutorials/io`
+ - :doc:`../Tutorials/convert`
+ - :doc:`../Tutorials/specfile_to_hdf5`
+
+Usage
+-----
+
+::
+
+    silx convert [-h] [--file-pattern FILE_PATTERN] [-o OUTPUT_URI]
+                    [-m MODE] [--begin BEGIN] [--end END] [--add-root-group]
+                    [--overwrite-data] [--min-size MIN_SIZE]
+                    [--chunks [CHUNKS]] [--compression [COMPRESSION]]
+                    [--compression-opts COMPRESSION_OPTS] [--shuffle]
+                    [--fletcher32] [--debug]
+                    [input_files [input_files ...]]
+
+
+
+Options
+-------
+
+::
+
+  input_files           Input files (EDF, TIFF, SPEC...). When specifying
+                        multiple files, you cannot specify both fabio images
+                        and SPEC files. Multiple SPEC files will simply be
+                        concatenated, with one entry per scan. Multiple image
+                        files will be merged into a single entry with a stack
+                        of images.
+
+
+  -h, --help            show this help message and exit
+  --file-pattern FILE_PATTERN
+                        File name pattern for loading a series of indexed
+                        image files (toto_%04d.edf). This argument is
+                        incompatible with argument input_files. If an output
+                        URI with a HDF5 path is provided, only the content of
+                        the NXdetector group will be copied there. If no HDF5
+                        path, or just "/", is given, a complete NXdata
+                        structure will be created.
+  -o OUTPUT_URI, --output-uri OUTPUT_URI
+                        Output file name (HDF5). An URI can be provided to
+                        write the data into a specific group in the output
+                        file: /path/to/file::/path/to/group. If not provided,
+                        the filename defaults to a timestamp: YYYYmmdd-
+                        HHMMSS.h5
+  -m MODE, --mode MODE  Write mode: "r+" (read/write, file must exist), "w"
+                        (write, existing file is lost), "w-" (write, fail if
+                        file exists) or "a" (read/write if exists, create
+                        otherwise)
+  --begin BEGIN         First file index, or first file indices to be
+                        considered. This argument only makes sense when used
+                        together with --file-pattern. Provide as many start
+                        indices as there are indices in the file pattern, separated
+                        by commas. Examples: "--filepattern toto_%d.edf
+                        --begin 100", "--filepattern toto_%d_%04d_%02d.edf
+                        --begin 100,2000,5".
+  --end END             Last file index, or last file indices to be
+                        considered. The same rules as with argument --begin
+                        apply. Example: "--filepattern toto_%d_%d.edf --end
+                        199,1999"
+  --add-root-group      This option causes each input file to be written to a
+                        specific root group with the same name as the file.
+                        When merging multiple input files, this can help
+                        preventing conflicts when datasets have the same name
+                        (see --overwrite-data). This option is ignored when
+                        using --file-pattern.
+  --overwrite-data      If the output path exists and an input dataset has the
+                        same name as an existing output dataset, overwrite the
+                        output dataset (in modes "r+" or "a").
+  --min-size MIN_SIZE   Minimum number of elements required to be in a dataset
+                        to apply compression or chunking (default 500).
+  --chunks <CHUNKS>     Chunk shape. Provide an argument that evaluates as a
+                        python tuple (e.g. "(1024, 768)"). If this option is
+                        provided without specifying an argument, the h5py
+                        library will guess a chunk for you. Note that if you
+                        specify an explicit chunking shape, it will be applied
+                        identically to all datasets with a large enough size
+                        (see --min-size).
+  --compression <COMPRESSION>
+                        Compression filter. By default, the datasets in the
+                        output file are not compressed. If this option is
+                        specified without argument, the GZIP compression is
+                        used. Additional compression filters may be available,
+                        depending on your HDF5 installation.
+  --compression-opts COMPRESSION_OPTS
+                        Compression options. For "gzip", this may be an
+                        integer from 0 to 9, with a default of 4. This is only
+                        supported for GZIP.
+  --shuffle             Enables the byte shuffle filter. This may improve the
+                        compression ratio for block oriented compressors like
+                        GZIP or LZF.
+  --fletcher32          Adds a checksum to each chunk to detect data
+                        corruption.
+  --debug               Set logging system in debug mode
+
+
+Examples of usage
+-----------------
+
+
+Simple single file conversion to new output file::
+
+    silx convert 31oct98.dat -o 31oct98.h5
+
+Concatenation of all SPEC files in the current directory::
+
+    silx convert *.dat -o all_SPEC.h5
+
+Appending a file to an existing output file::
+
+    silx convert ch09__mca_0005_0000_0008.edf -o archive.h5::/ch09__mca_0005_0000_0008 -m a --compression
+
+Merging a list of single frame EDF files into a multiframe HDF5 file::
+
+    silx convert --file-pattern ch09__mca_0005_0000_%d.edf -o ch09__mca_0005_0000_multiframe.h5
diff --git a/doc/source/applications/img/silx-view-hdf5.png b/doc/source/applications/img/silx-view-hdf5.png
new file mode 100644
index 0000000..96449fd
--- /dev/null
+++ b/doc/source/applications/img/silx-view-hdf5.png
diff --git a/doc/source/applications/img/silx-view-image.png b/doc/source/applications/img/silx-view-image.png
new file mode 100644
index 0000000..85b0362
--- /dev/null
+++ b/doc/source/applications/img/silx-view-image.png
diff --git a/doc/source/applications/img/silx-view-table.png b/doc/source/applications/img/silx-view-table.png
new file mode 100644
index 0000000..b71728c
--- /dev/null
+++ b/doc/source/applications/img/silx-view-table.png
diff --git a/doc/source/applications/index.rst b/doc/source/applications/index.rst
new file mode 100644
index 0000000..2601e2c
--- /dev/null
+++ b/doc/source/applications/index.rst
@@ -0,0 +1,17 @@
+
+Applications documentation
+==========================
+
+While *silx* is first and foremost a Python library to be used by developers,
+a set of command line applications is provided to use some key features of
+the library without knowing anything about Python.
+
+To see the list of all available commands, type the following command in a terminal::
+
+    silx help
+
+.. toctree::
+   :maxdepth: 1
+
+   view
+   convert
diff --git a/doc/source/applications/view.rst b/doc/source/applications/view.rst
new file mode 100644
index 0000000..694f95d
--- /dev/null
+++ b/doc/source/applications/view.rst
@@ -0,0 +1,60 @@
+
+silx view
+=========
+
+Purpose
+-------
+
+The *silx view* command is provided to open data files
+in a graphical user interface. It allows to select a particular
+piece of data or a particular header in structured data formats,
+and to view this data in plot widgets or in simple table views.
+
+
+.. |imgViewImg| image:: img/silx-view-image.png
+   :height: 300px
+   :align: middle
+
+.. |imgViewTable| image:: img/silx-view-table.png
+   :height: 300px
+   :align: middle
+
+.. |imgViewHdf5| image:: img/silx-view-hdf5.png
+   :height: 300px
+   :align: middle
+
+.. list-table::
+   :widths: 1 2
+
+   * - |imgViewImg|
+     - Image view
+   * - |imgViewTable|
+     - Viewing raw data as values in a table
+   * - |imgViewHdf5|
+     - Viewing metadata and HDF5 attributes
+
+
+Usage
+-----
+
+::
+
+    silx view [-h] [--debug] [--use-opengl-plot] [files [files ...]]
+
+
+Options
+-------
+
+  -h, --help           Show this help message and exit
+  --debug              Set logging system in debug mode
+  --use-opengl-plot    Use OpenGL for plots (instead of matplotlib)
+
+
+Examples of usage
+-----------------
+
+::
+
+    silx view 31oct98.dat
+    silx view *.edf
+    silx view myfile.h5