.. _digitalsurf-format:

DigitalSurf format (SUR & PRO)
------------------------------

``.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 (0,1)                                                      |
+-----------------+---------------+------------------------------------------------------------------------------+
| 1               | 1             | ``.pro``: Spectrum Series (based on axes name), Profile Series (default)     |
+-----------------+---------------+------------------------------------------------------------------------------+
| 1               | 2             | ``.sur``: RGBImage Series (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
^^^^^^^^^^^^^

.. automodule:: rsciio.digitalsurf
   :members:
