surfacetopography 0.91.2__py3.6-linux-x86_64.egg

SurfaceTopography/HeightContainer.py

@@ -0,0 +1,315 @@
+#
+# Copyright 2019-2020 Lars Pastewka
+#           2019-2020 Antoine Sanner
+#           2019 Michael Röttger
+#
+# ### MIT license
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+#
+
+"""
+Base class for geometric topogography descriptions
+"""
+
+import abc
+
+from NuMPI import MPI
+
+# Standardized entries for the info dictionary
+
+# Length unit of the measurement. The unit applies to both lateral and heights.
+# Data type: str
+INFO_UNIT = 'unit'
+# Data and time of the data acquisition.
+# Data type: datetime.datetime
+INFO_ACQUISITION_TIME = 'acquisition_time'
+
+
+class AbstractHeightContainer(object):
+    """
+    Base class for all containers storing height information.
+
+    The member dictionary `_functions` contains a list of functions that
+    can be executed on this specific container.
+
+    The dictionary itself is owned by the interface,
+    `UniformTopographyInterface` and `NonuniformLineScanInterface`. This is
+    because the functions are determined by the type of topography that is
+    represented, not by the pipeline hierarchy. For example, convertes that
+    convert uniform to nonuniform and vice versa need to have the respective
+    interface of the format they are converting to.
+    """
+
+    class Error(Exception):
+        # pylint: disable=missing-docstring
+        pass
+
+    def __init__(self, info={}, communicator=MPI.COMM_WORLD):
+        self._info = info.copy()
+        self._communicator = communicator
+
+    def apply(self, name, *args, **kwargs):
+        self._functions[name](self, *args, **kwargs)
+
+    def __getattr__(self, name):
+        if name in self._functions:
+            def func(*args, **kwargs):
+                return self._functions[name](self, *args, **kwargs)
+
+            func.__doc__ = self._functions[name].__doc__
+            return func
+        else:
+            raise AttributeError(
+                "Unkown attribute '{}' and no analysis or pipeline function "
+                "of this name registered (class {}). Available functions: {}"
+                .format(name, self.__class__.__name__,
+                        ', '.join(self._functions.keys())))
+
+    def __dir__(self):
+        return sorted(super().__dir__() + [*self._functions])
+
+    def __getstate__(self):
+        """
+        Upon pickling, it is called and the returned object is pickled as the
+        contents for the instance.
+        """
+        return self._info
+
+    def __setstate__(self, state):
+        """
+        Upon unpickling, it is called with the unpickled state.
+        The argument `state` is the result of `__getstate__`.
+        """
+        self._info = state
+        self._communicator = MPI.COMM_WORLD
+
+    @property
+    @abc.abstractmethod
+    def is_periodic(self):
+        """Return whether the topography is periodically repeated at the
+        boundaries."""
+        raise NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def dim(self):
+        """Returns 1 for line scans and 2 for topography maps."""
+        raise NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def physical_sizes(self, ):
+        """Return the physical sizes of the topography."""
+        raise NotImplementedError
+
+    @property
+    def info(self, ):
+        """
+        Return the info dictionary. The info dictionary contains auxiliary data
+        found in the topography data file but not directly used by PyCo.
+
+        The dictionary can contain any type of information. There are a few
+        standardized keys, listed in the following.
+
+        Standardized keys:
+        unit : str
+            Unit of the topography. The unit information applies to the lateral
+            units (the physical size) as well as to heights units. Examples:
+            'µm', 'nm'.
+        datetime : :obj:`datetime`
+            Date and time of the measurement.
+        """
+        return self._info
+
+    @property
+    def communicator(self):
+        """Return the MPI communicator object."""
+        return self._communicator
+
+    def pipeline(self):
+        return [self]
+
+
+class DecoratedTopography(AbstractHeightContainer):
+    """
+    Base class of topographies with parent. Having a parent means that the
+    data is owned by the parent, but the present class performs
+    transformations on that data. This is a simple realization of a
+    processing pipeline. Note that child topographies don't store their
+    own physical_sizes etc. but pass this information through to the parent.
+    """
+
+    def __init__(self, topography, info={}):
+        """
+        Arguments
+        ---------
+        topography : SurfaceTopography
+            The parent topography.
+        """
+        super().__init__(info=info)
+        assert isinstance(topography, AbstractHeightContainer)
+        self.parent_topography = topography
+        self._communicator = self.parent_topography.communicator
+
+    def __getstate__(self):
+        """ is called and the returned object is pickled as the contents for
+            the instance
+        """
+        state = super().__getstate__(), self.parent_topography
+        return state
+
+    def __setstate__(self, state):
+        """ Upon unpickling, it is called with the unpickled state
+        Keyword Arguments:
+        state -- result of __getstate__
+        """
+        superstate, self.parent_topography = state
+        super().__setstate__(superstate)
+
+    @property
+    def info(self):
+        """ Return info dictionary """
+        info = self.parent_topography.info.copy()
+        info.update(self._info)
+        return info
+
+    def pipeline(self):
+        return self.parent_topography.pipeline() + [self]
+
+
+class TopographyInterface(object):
+    @classmethod
+    def register_function(cls, name, function):
+        cls._functions.update({name: function})
+
+
+class UniformTopographyInterface(TopographyInterface, metaclass=abc.ABCMeta):
+    _functions = {}
+
+    @property
+    def is_uniform(self):
+        return True
+
+    @property
+    def is_domain_decomposed(self):
+        return self.nb_grid_pts != self.nb_subdomain_grid_pts
+
+    @property
+    def communicator(self):
+        # default value is COMM_SELF because sometimes NON-MPI readers that
+        # do not set the communicator value are used in MPI Programs.
+        # See discussion in issue #166
+        return MPI.COMM_SELF
+
+    @property
+    @abc.abstractmethod
+    def nb_grid_pts(self):
+        raise NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def pixel_size(self):
+        return NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def area_per_pt(self):
+        return NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def has_undefined_data(self):
+        return NotImplementedError
+
+    @abc.abstractmethod
+    def positions(self):
+        """
+        Returns array containing the lateral positions.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def heights(self):
+        """
+        Returns array containing the topography data.
+        """
+        return NotImplementedError
+
+    def positions_and_heights(self):
+        """
+        Returns array containing the lateral positions and the topography
+        data.
+        """
+        p = self.positions()
+        h = self.heights()
+        try:
+            x, y = p
+            return x, y, h
+        except ValueError:
+            return p, h
+
+    def __getitem__(self, i):
+        return self.heights()[i]
+
+
+class NonuniformLineScanInterface(TopographyInterface, metaclass=abc.ABCMeta):
+    _functions = {}
+
+    @property
+    def is_uniform(self):
+        return False
+
+    @property
+    @abc.abstractmethod
+    def nb_grid_pts(self):
+        raise NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def x_range(self):
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def positions(self):
+        """
+        Returns array containing the lateral positions.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def heights(self):
+        """
+        Returns array containing the topography data.
+        """
+        raise NotImplementedError
+
+    def positions_and_heights(self):
+        """
+        Returns array containing the lateral positions and the topography
+        data.
+        """
+        return self.positions(), self.heights()
+
+    @property
+    def is_MPI(self):
+        return False
+
+    def __getitem__(self, i):
+        return self.positions()[i], self.heights()[i]

SurfaceTopography/IO/DI.py

@@ -0,0 +1,261 @@
+#
+# Copyright 2019-2020 Lars Pastewka
+#           2020 Michael Röttger
+#           2019 Antoine Sanner
+#
+# ### MIT license
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+#
+
+#
+# The DI file format is described in detail here:
+# http://www.physics.arizona.edu/~smanne/DI/software/fileformats.html
+#
+
+import re
+from datetime import datetime
+
+import numpy as np
+
+from SurfaceTopography import Topography
+
+from .FromFile import get_unit_conversion_factor, height_units, \
+    mangle_height_unit
+from .Reader import ReaderBase, ChannelInfo
+
+
+###
+
+class DIReader(ReaderBase):
+    _format = 'di'
+    _name = 'Veeco (Digital Instruments) Nanoscope'
+    _description = '''
+Digitial Instruments Nanoscope files typically have a three-digit number as
+the file extension (.001, .002, .003, ...). This format contains information
+on the physical size of the topography map as well as its units. The reader
+supports V4.3 and later version of the format.
+'''
+
+    def __init__(self, fobj):
+        """
+        Load Digital Instrument's Nanoscope files.
+
+        Arguments
+        ---------
+        fobj : filename or file object
+             File or data stream to open.
+        """
+        self._fobj = fobj
+        close_file = False
+        if not hasattr(fobj, 'read'):
+            fobj = open(fobj, 'rb')
+            close_file = True
+        try:
+            parameters = []
+            section_name = None
+            section_dict = {}
+
+            L = fobj.readline().decode('latin-1').strip()
+            while L and L.lower() != r'\*file list end':
+                if L.startswith('\\*'):
+                    if section_name is not None:
+                        parameters += [(section_name, section_dict)]
+                    new_section_name = L[2:].lower()
+                    if section_name is None:
+                        if new_section_name != 'file list':
+                            raise IOError("Header must start with the "
+                                          "'File list' section.")
+                    section_name = new_section_name
+                    section_dict = {}
+                elif L.startswith('\\'):
+                    if section_name is None:
+                        raise IOError('Encountered key before section '
+                                      'header.')
+                    s = L[1:].split(': ', 1)
+                    try:
+                        key, value = s
+                    except ValueError:
+                        key, = s
+                        value = ''
+                    section_dict[key.lower()] = value.strip()
+                else:
+                    raise IOError(
+                        "Header line '{}' does not start with a slash."
+                        .format(L))
+                L = fobj.readline().decode('latin-1').strip()
+            if section_name is None:
+                raise IOError('No sections found in header.')
+            parameters += [(section_name, section_dict)]
+
+            self._channels = []
+            self._offsets = []
+
+            scanner = {}
+            info = {}
+            for n, p in parameters:
+                if n == 'file list':
+                    if 'date' in p:
+                        info['acquisition_time'] = \
+                            datetime.strptime(p['date'],
+                                              '%I:%M:%S %p %a %b %d %Y')
+                elif n == 'scanner list' or n == 'ciao scan list':
+                    scanner.update(p)
+                elif n == 'ciao image list':
+                    image_data_key = re.match(r'^S \[(.*?)\] ',
+                                              p['@2:image data']).group(1)
+
+                    nx = int(p['samps/line'])
+                    ny = int(p['number of lines'])
+
+                    s = p['scan size'].split(' ', 2)
+                    sx = float(s[0])
+                    sy = float(s[1])
+
+                    xy_unit = mangle_height_unit(s[2])
+                    offset = int(p['data offset'])
+                    self._offsets.append(offset)
+
+                    length = int(p['data length'])
+                    elsize = int(p['bytes/pixel'])
+                    if elsize != 2:
+                        raise IOError(
+                            "Don't know how to handle {} bytes per pixel "
+                            "data.".format(elsize))
+                    if nx * ny * elsize != length:
+                        raise IOError(
+                            'Data block physical_sizes differs from extend '
+                            'of surface.')
+
+                    scale_re = re.match(
+                        r'^V \[(.*?)\] \(([0-9\.]+) (.*)\/LSB\) (.*) '
+                        r'(.*)', p['@2:z scale'])
+                    quantity = scale_re.group(1).lower()
+                    hard_scale = float(scale_re.group(4)) / 65536
+                    hard_unit = scale_re.group(5)
+
+                    s = scanner['@' + quantity].split()
+                    if s[0] != 'V' or len(s) < 2:
+                        raise ValueError('Malformed Nanoscope DI file.')
+                    soft_scale = float(s[1])
+
+                    height_unit = None
+                    hard_to_soft = 1.0
+                    if len(s) > 2:
+                        # Check units
+                        height_unit, soft_unit = s[2].split('/')
+                        hard_to_soft = get_unit_conversion_factor(hard_unit,
+                                                                  soft_unit)
+                        if hard_to_soft is None:
+                            raise ValueError(
+                                "Units for hard (={}) and soft (={}) "
+                                "scale differ for '{}'. Don't know how "
+                                "to handle this.".format(hard_unit,
+                                                         soft_unit,
+                                                         image_data_key))
+                    if height_unit in height_units:
+                        height_unit = mangle_height_unit(height_unit)
+                        if xy_unit != height_unit:
+                            fac = get_unit_conversion_factor(xy_unit,
+                                                             height_unit)
+                            sx *= fac
+                            sy *= fac
+                            xy_unit = height_unit
+                        unit = height_unit
+                    else:
+                        unit = (xy_unit, height_unit)
+
+                    channel_info = info.copy()
+                    channel_info.update(dict(
+                        unit=unit,
+                        height_scale_factor=hard_scale * hard_to_soft *
+                        soft_scale))
+                    channel = ChannelInfo(self,
+                                          len(self._channels),
+                                          name=image_data_key,
+                                          dim=2,
+                                          nb_grid_pts=(nx, ny),
+                                          physical_sizes=(sx, sy),
+                                          periodic=False,
+                                          info=channel_info)
+                    self._channels.append(channel)
+        finally:
+            if close_file:
+                fobj.close()
+
+    @property
+    def channels(self):
+        return self._channels
+
+    def topography(self, channel_index=None, physical_sizes=None,
+                   height_scale_factor=None, info={}, periodic=False,
+                   subdomain_locations=None, nb_subdomain_grid_pts=None):
+        if channel_index is None:
+            channel_index = self._default_channel_index
+
+        if subdomain_locations is not None or \
+                nb_subdomain_grid_pts is not None:
+            raise RuntimeError(
+                'This reader does not support MPI parallelization.')
+        close_file = False
+        if not hasattr(self._fobj, 'read'):
+            fobj = open(self._fobj, 'rb')
+            close_file = True
+        else:
+            fobj = self._fobj
+
+        channel = self._channels[channel_index]
+        sx, sy = self._check_physical_sizes(physical_sizes,
+                                            channel.physical_sizes)
+
+        nx, ny = channel.nb_grid_pts
+
+        offset = self._offsets[channel_index]
+        dtype = np.dtype('<i2')
+
+        ###################################
+
+        fobj.seek(offset)
+        rawdata = fobj.read(nx * ny * dtype.itemsize)
+        unscaleddata = np.frombuffer(rawdata, count=nx * ny,
+                                     dtype=dtype).reshape(nx, ny)
+
+        # internal information from file
+        _info = dict(unit=channel.info["unit"], data_source=channel.name)
+        _info.update(info)
+        if 'acquisition_time' in channel.info:
+            _info['acquisition_time'] = channel.info['acquisition_time']
+
+        # the orientation of the heights is modified in order to match
+        # the image of gwyddion when plotted with imshow(t.heights().T)
+        # or pcolormesh(t.heights().T) for origin in lower left and
+        # with inverted y axis (cartesian coordinate system)
+        surface = Topography(np.fliplr(unscaleddata.T), (sx, sy), info=_info,
+                             periodic=periodic)
+        if height_scale_factor is None:
+            height_scale_factor = channel.info["height_scale_factor"]
+        surface = surface.scale(height_scale_factor)
+
+        if close_file:
+            fobj.close()
+
+        return surface
+
+    channels.__doc__ = ReaderBase.channels.__doc__
+    topography.__doc__ = ReaderBase.topography.__doc__