File_Writer for DigitalSurf files

doc/user_guide/supported_formats/digitalsurf.rst

@@ -3,16 +3,54 @@
 DigitalSurf format (SUR & PRO)
 ------------------------------
 
-The ``.sur`` and ``.pro`` files are a format developed by the digitalsurf company to handle various types of
-scientific measurements data such as profilometer, SEM, AFM, RGB(A) images, multilayer
-surfaces and profiles. Even though it is essentially a surfaces format, 1D signals
-are supported for spectra and spectral maps. Specifically, this file format is used
-by Attolight SA for its scanning electron microscope cathodoluminescence
-(SEM-CL) hyperspectral maps. Metadata parsing is supported, including user-specific
-metadata, as well as the loading of files containing multiple objects packed together.
-
-The plugin was developed based on the MountainsMap software documentation, which
-contains a description of the binary format.
+``.sur`` and ``.pro`` is a format developed by digitalsurf to import/export data in the MountainsMap scientific 
+analysis software. Target datasets are originally (micro)-topography maps and profile from imaging instruments: 
+SEM, AFM, profilometery etc. RGB(A) images, multilayer surfaces and profiles are also supported. Even though it 
+is essentially a surfaces format, 1D signals are supported for spectra and spectral maps. Specifically, this is 
+the format used by Attolight for saving SEM-cathodoluminescence (SEM-CL) hyperspectral maps. This plugin was 
+developed based on the MountainsMap software documentation.
+
+Support for loading ``.sur`` and ``.pro`` files is complete, including parsing of custom metadata, and opening of 
+files containing multiple objects. Some rare, deprecated object types (e.g. force curves) are not supported, due 
+to no example data being available. Those can be added upon request to the module, if provided with example data
+and a explanations. Unlike hyperspy.signal, ``.sur`` and ``.pro`` objects can be used to represent heterogeneous
+data. For instance, float (topography) and int (rgb data) data can coexist along the same navigation dimension. 
+Those are casted to a homogeneous floating-point representation upon loading.
+
+Support for data saving is partial, as ``.sur`` and ``.pro`` do not support all features of hyperspy signals. Up 
+to 3d data arrays with either 1d (series of images) or 2d (spectral maps) navigation space can be saved. ``.sur`` 
+and ``.pro`` also do not support non-uniform axes and fitted models. Finally, MountainsMap maps intensities along 
+an axis with constant spacing between numbers by enforcing an integer-representation of the data with scaling and 
+offset. This means that export from float data is inherently lossy.
+
+Within these limitations, all features from ``.sur`` and ``.pro`` fileformats are supported. Data compression and
+custom metadata allows a good interoperability of hyperspy and Mountainsmap. The file writer splits a signal into 
+the suitable digitalsurf dataobject. Primarily by inspecting its dimension and datatype. If ambiguity remains, it
+inspects the names of signal axes and ``metadata.Signal.quantity``. The criteria are listed here below:
+
++-----------------+---------------+------------------------------------------------------------------------------+
+| Nav. dimension  | Sig dimension | Extension and MountainsMap subclass                                          |
++=================+===============+==============================================================================+
+| 0               | 1             | ``.pro``: Spectrum (based on axes name), Profile (default)                   |
++-----------------+---------------+------------------------------------------------------------------------------+
+| 0               | 2             | ``.sur``: BinaryImage (based on dtype), RGBImage (based on dtype),           |
+|                 |               | Surface (default)                                                            |
++-----------------+---------------+------------------------------------------------------------------------------+
+| 1               | 0             | ``.pro``: same as (1,0)                                                      |
++-----------------+---------------+------------------------------------------------------------------------------+
+| 1               | 1             | ``.pro``: Spectrum Serie (based on axes name), Profile Serie (default)       |
++-----------------+---------------+------------------------------------------------------------------------------+
+| 1               | 2             | ``.sur``: RGBImage Serie (based on dtype), Surface Series (default)          |
++-----------------+---------------+------------------------------------------------------------------------------+
+| 2               | 0             | ``.sur``: same as (0,2)                                                      |
++-----------------+---------------+------------------------------------------------------------------------------+
+| 2               | 1             | ``.sur``: hyperspectralMap (default)                                         |
++-----------------+---------------+------------------------------------------------------------------------------+
+
+Axes named one of ``Wavelength``, ``Energy``, ``Energy Loss`` or  ``E`` are considered spectral. A quantity named 
+one of ``Height``, ``Altitude``, ``Elevation``, ``Depth`` or ``Z`` is  considered a surface. The difference between 
+Surface and IntensitySurface stems from the AFM / profilometry origin of MountainsMap. "Surface" has its proper 
+meaning of being a 2d-subset of 3d space, whereas "IntensitySurface" is a mere 2D mapping of an arbitrary quantity.
 
 API functions
 ^^^^^^^^^^^^^