surfacetopography 0.91.2__py3.6-linux-x86_64.egg

SurfaceTopography/IO/H5.py

@@ -0,0 +1,79 @@
+#
+# Copyright 2019-2020 Lars Pastewka
+#           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.
+#
+
+from .. import Topography
+from .Reader import ReaderBase, ChannelInfo
+
+
+class H5Reader(ReaderBase):
+    _format = 'h5'
+    _name = 'Hierarchical data format (HDF5)'
+    _description = '''
+Import filter for [HDF5](https://support.hdfgroup.org/HDF5/) files provided
+within the contact mechanics challenge. The reader looks for a two-dimensional
+array named `surface`. HDF5 files do not store units or physical sizes. These
+need to be manually provided by the user.
+
+The original contact mechanics challenge data can be downloaded
+[here](https://www.lmp.uni-saarland.de/index.php/research-topics/contact-mechanics-challenge-announcement/).
+    '''  # noqa: E501
+
+    def __init__(self, fobj):
+        self._h5 = None
+        import h5py
+        self._h5 = h5py.File(fobj, 'r')
+
+    def close(self):
+        if self._h5 is not None:
+            self._h5.close()
+
+    @property
+    def channels(self):
+        return [ChannelInfo(self,
+                            0,  # channel index
+                            name='Default',
+                            dim=len(self._h5['surface'].shape),
+                            nb_grid_pts=self._h5['surface'].shape)]
+
+    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 subdomain_locations is not None or \
+                nb_subdomain_grid_pts is not None:
+            raise RuntimeError(
+                'This reader does not support MPI parallelization.')
+        if channel_index is None:
+            channel_index = self._default_channel_index
+        if channel_index != 0:
+            raise RuntimeError('HDF5 reader only supports a single channel')
+        size = self._check_physical_sizes(physical_sizes)
+        t = Topography(self._h5['surface'][...], size, info=info,
+                       periodic=periodic)
+        if height_scale_factor is not None:
+            t = t.scale(height_scale_factor)
+        return t
+
+    channels.__doc__ = ReaderBase.channels.__doc__
+    topography.__doc__ = ReaderBase.topography.__doc__

SurfaceTopography/IO/IBW.py

@@ -0,0 +1,176 @@
+#
+# Copyright 2019-2020 Lars Pastewka
+#           2019-2020 Michael Röttger
+#           2019 Kai Haase
+#
+# ### 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.
+#
+
+import numpy as np
+from io import TextIOBase
+
+from igor.binarywave import load as loadibw
+
+from .. import Topography
+from .Reader import ReaderBase, ChannelInfo
+
+
+class IBWReader(ReaderBase):
+    _format = 'ibw'
+    _name = 'Igor binary wave'
+    _description = '''
+Igor binary wave is a container format of the
+[Igor Pro](https://www.wavemetrics.com/products/igorpro/programming)
+language. This format is used by AFMs from Asylum Research (now Oxford
+Instruments) to store topography information. This format contains information
+on the physical size of the topography map as well as its units.
+'''
+
+    # Reads in the positions of all the data and metadata
+    def __init__(self, file_path):
+
+        # depending from where this function is called, file_path might already
+        # be a filestream
+        already_open = False
+        if not hasattr(file_path, 'read'):
+            f = open(file_path, "rb")
+        else:
+            already_open = True
+            if isinstance(file_path, TextIOBase):
+                # file was opened without the 'b' option, so read its buffer to
+                # get the binary data
+                f = file_path.buffer
+            else:
+                f = file_path
+
+        # This catches and closes on its own
+        try:
+            file = loadibw(f)
+        except Exception:
+            if not f.closed:
+                if not already_open:
+                    f.close()
+            raise RuntimeError('Invalid file format.')
+
+        if file['version'] != 5:
+            raise RuntimeError('Only IBW version 5 supported!')
+
+        self.data = file['wave']
+
+        # the first two labels are of x and y axis. we cannot read those
+        self._channel_names = [channel.decode() for channel in
+                               self.data['labels'][2][1:]]
+        self._default_channel = 0
+
+        #
+        # Read physical sizes from file, since all data
+        # has already been loaded, we can calculate it here
+        #
+        height_data = self.data['wData']
+
+        # TODO is it always like this?
+        assert len(height_data.shape) == 3, \
+            "We expect all channels being coded in to one wave and all are " \
+            "2D. This is not true somehow, cannot proceed."
+        nx, ny, num_channels = height_data.shape
+
+        # ensure that there are not too many channel names
+        self._channel_names = self._channel_names[:num_channels]
+
+        # add channel names for all channels without name
+        no_name_idx = 1
+        while len(self._channel_names) < num_channels:
+            self._channel_names.append("no name ({})".format(no_name_idx))
+            no_name_idx += 1
+
+        #
+        # Decode units
+        #
+        def decode_unit_entry(u):
+            return u.tobytes().partition(b'\0')[0].decode('latin-1')
+
+        data_unit = decode_unit_entry(self.data['wave_header']['dataUnits'])
+        x_unit = decode_unit_entry(self.data['wave_header']['dimUnits'][0])
+        y_unit = decode_unit_entry(self.data['wave_header']['dimUnits'][1])
+
+        # the following is not necessary, we could handle different units by
+        # rescaling, however I'll leave it like this for now, print some
+        # message so we know what to do if a file occurs which does not fulfill
+        # this assumption
+        assert data_unit == x_unit == y_unit, \
+            "So far, data units and dimension units must be all the same. " +\
+            "data unit: '{}', x unit: '{}', y unit: '{}'".format(data_unit,
+                                                                 x_unit,
+                                                                 y_unit)
+
+        self._data_unit = data_unit
+        #
+        # Decode sizes
+        #
+        sfA = self.data['wave_header']['sfA']
+        self._physical_sizes = (nx * sfA[0], ny * sfA[1])
+        # Comment in C header file on these fields: Index value for element e
+        # of dimension d = sfA[d]*e + sfB[d]. sfB is left out here, because we
+        # are interested in the width and height, not the absolute offsets.
+
+        #
+        # Build channel information
+        #
+        self._channels = [
+            ChannelInfo(self, i, name=cn, dim=2, nb_grid_pts=(nx, ny),
+                        physical_sizes=self._physical_sizes)
+            for i, cn in enumerate(self._channel_names)]
+
+        # Shall we use the channel names in order to assign a unit as Gwyddion
+        # does?
+
+    @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.')
+
+        height_data = self.data['wData']
+        height_data = np.fliplr(height_data[:, :, channel_index].copy())
+
+        if physical_sizes is None:
+            physical_sizes = self._physical_sizes
+
+        topo = Topography(height_data, physical_sizes,
+                          info=info,
+                          periodic=periodic)
+        # we could pass the data units here, but they dont seem to be always
+        # correct for all channels?!
+
+        if height_scale_factor is not None:
+            topo = topo.scale(height_scale_factor)
+
+        return topo

SurfaceTopography/IO/MI.py

@@ -0,0 +1,307 @@
+#
+# Copyright 2019-2020 Lars Pastewka
+#           2020 Michael Röttger
+#           2019-2020 Kai Haase
+#           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.
+#
+
+import numpy as np
+
+from .. import Topography
+from .Reader import ReaderBase, CorruptFile, ChannelInfo
+from .FromFile import mangle_height_unit
+from io import TextIOBase
+
+image_head = b'fileType      Image\n'
+spec_head = b'fileType      Spectroscopy\n'
+
+magic_data = b'data          \n'
+magic_data_binary = b'data          BINARY\n'
+magic_data_binary32 = b'data          BINARY_32\n'
+magic_data_ascii = b'data          ASCII'
+
+
+class MIReader(ReaderBase):
+    _format = 'mi'
+    _name = 'Molecular imaging data file'
+    _description = '''
+This reader opens Agilent Technologies (Molecular Imaging) AFM files saved
+in the MI format. This format contains information on the physical size of the
+topography map as well as its units.
+'''
+
+    # Reads in the positions of all the data and metadata
+    def __init__(self, file_path):
+        self.file_path = file_path
+
+        # Start of the data in the file
+        self.data_start = None
+        # If image oder spectroscopy
+        self.is_image = None
+        # Format of the saved data
+        self.data_type = None
+
+        self.mifile = None
+
+        # Process the header and read in metadata
+        self.process_header()
+
+    def process_header(self):
+
+        already_open = False
+        if not hasattr(self.file_path, 'read'):
+            f = open(self.file_path, "rb")
+        else:
+            already_open = True
+            if isinstance(self.file_path, TextIOBase):
+                # file was opened without the 'b' option, so read its buffer
+                # to get the binary data
+                f = self.file_path.buffer
+            else:
+                f = self.file_path
+
+        try:
+            self.lines = f.readlines()
+
+            # Find out if image or spectroscopy
+            if self.lines[0] == image_head:
+                self.is_image = True
+            elif self.lines[0] == spec_head:
+                self.is_image = False
+            else:
+                raise CorruptFile
+
+            # Find the start of the height data and denote data type
+            if magic_data in self.lines:
+                header_size = self.lines.index(magic_data)
+                self.data_type = 'text'
+            elif magic_data_binary in self.lines:
+                header_size = self.lines.index(magic_data_binary)
+                self.data_type = 'binary'
+            elif magic_data_binary32 in self.lines:
+                header_size = self.lines.index(magic_data_binary32)
+                self.data_type = 'binary32'
+            elif magic_data_ascii in self.lines:
+                header_size = self.lines.index(magic_data_ascii)
+                self.data_type = 'ascii'
+            else:
+                raise CorruptFile
+
+            # Save start of data for later reading of the matrix
+            self.data_start = header_size + 1
+
+            # Create mifile from header, reading out meta data and channel info
+            if self.is_image:
+                self.mifile = read_header_image(self.lines[1:header_size])
+            else:  # TODO
+                self.mifile = read_header_spect(self.lines[1:header_size])
+
+            # Reformat the metadata
+            for buf in self.mifile.channels:
+                buf.meta['name'] = buf.name
+                buf.meta['unit'] = mangle_height_unit(
+                    buf.meta.pop('bufferUnit'))
+                buf.meta['range'] = buf.meta.pop('bufferRange')
+                buf.meta['label'] = buf.meta.pop('bufferLabel')
+
+            self._physical_sizes = float(self.mifile.meta['xLength']), \
+                float(self.mifile.meta['yLength'])
+            self._nb_grid_pts = int(self.mifile.meta['xPixels']), \
+                int(self.mifile.meta['yPixels'])
+
+        finally:
+            if not already_open:
+                f.close()
+
+    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.')
+
+        output_channel = self.mifile.channels[channel_index]
+
+        buffer = b''.join(self.lines[self.data_start:])
+        buffer = [chr(_) for _ in buffer]
+
+        # Read height data
+        if self.is_image:
+            if self.data_type == 'binary':
+                dt = "i2"
+                encode_length = 2
+                type_range = 32768
+            elif self.data_type == 'binary32':
+                dt = "i4"
+                encode_length = 4
+                type_range = 2147483648
+            else:  # text or ascii
+                type_range = 32768
+
+            start = int(self.mifile.xres) * int(
+                self.mifile.yres) * encode_length * channel_index
+            end = int(self.mifile.xres) * int(
+                self.mifile.yres) * encode_length * (channel_index + 1)
+
+            data = ''.join(buffer[start:end])
+            out = np.frombuffer(str.encode(data, "raw_unicode_escape"), dt)
+            out = out.reshape((int(self.mifile.xres), int(self.mifile.yres)))
+
+            # Undo normalizing with range of data type
+            out = out / type_range
+
+            # If scan direction is upwards, flip the height map vertically
+            if self.mifile.meta['scanUp']:
+                out = np.flip(out, 0)
+
+            # Multiply the heights with the bufferRange
+            out *= float(output_channel.meta['range'])
+        else:
+            pass  # TODO
+
+        joined_meta = {**self.mifile.meta, **output_channel.meta}
+
+        # Initialize heights with transposed array in order to match Gwdyydion
+        # when plotted with pcolormesh(t.heights().T), except that the y axis
+        # is flipped because the origin is in lower left with pcolormesh;
+        # imshow(t.heights().T) shows the image like gwyddion
+        t = Topography(heights=out.T,
+                       physical_sizes=self._check_physical_sizes(
+                           physical_sizes, self._physical_sizes),
+                       info=joined_meta, periodic=periodic)
+        if height_scale_factor is not None:
+            t.scale(height_scale_factor)
+        return t
+
+    @property
+    def channels(self):
+        return [ChannelInfo(self, i, name=channel.meta['name'],
+                            dim=len(self._nb_grid_pts),
+                            nb_grid_pts=self._nb_grid_pts,
+                            physical_sizes=self._physical_sizes,
+                            info=channel.meta)
+                for i, channel in enumerate(self.mifile.channels)]
+
+    @property
+    def info(self):
+        """ Return all the available metadata as a dict. """
+        return self.mifile.meta
+
+    channels.__doc__ = ReaderBase.channels.__doc__
+    topography.__doc__ = ReaderBase.topography.__doc__
+
+
+def read_header_image(header):
+    """
+    Reads in global metadata and information about about included channels as
+    well as their metadata.
+    :param header: The header as a line of text.
+    :return:
+    MIFile item containing the metadata, with the channels as a list of
+    'buffers'.
+    """
+    # This object will store the file-wide metadata
+    mifile = MIFile()
+
+    # False while reading global metadata, gets true if we start to read in the
+    # channel info
+    reading_buffers = False
+
+    for line in header:
+        line = line.decode("utf-8")
+
+        # As soon as we see a line starting with 'bufferLabel', we know we are
+        # now reading in channels
+        if line.startswith('bufferLabel'):
+            # Create a new channel with the id as name
+            channel = Channel(name=str.strip(line[14:]))
+            mifile.channels.append(channel)
+            reading_buffers = True
+
+        if line[0] == ' ':
+            continue
+
+        # For all key value pairs in the file:
+        # Append to global metadata oder channel metadata, depending on our
+        # state
+        key = str.strip(line[:14])
+        value = str.strip(line[14:])
+
+        if reading_buffers:
+            mifile.channels[-1].meta[key] = value
+        else:
+            mifile.meta[key] = value
+
+        # Catch 'special' metadata
+        if key == "xPixels":
+            mifile.xres = value
+        elif key == "yPixels":
+            mifile.yres = value
+    return mifile
+
+
+def read_header_spect(header):
+    """
+    Reads in metadata out of the header.
+    :param header: The header.
+    :return:
+    MIFile item containing the metadata.
+    """
+    pass
+
+
+class Channel:
+    """
+    Class structure for a channel contained in the file.
+    Has a name and metadata (height data is not needed since it is returned
+    directly).
+    """
+
+    def __init__(self, name=None, meta=None):
+        if meta is None:
+            meta = dict()
+
+        self.name = name
+        self.meta = meta
+
+
+class MIFile:
+    """
+    Class structure for the while file. Has a list of channels, global metadata
+    and a nb_grid_pts.
+    """
+
+    def __init__(self, res=(0, 0), channels=None, meta=None):
+        if channels is None:
+            channels = list()
+        if meta is None:
+            meta = dict()
+
+        self.xres = res[0]
+        self.yres = res[1]
+        self.channels = channels
+        self.meta = meta

SurfaceTopography/IO/Matlab.py

@@ -0,0 +1,106 @@
+#
+# Copyright 2019-2020 Lars Pastewka
+#           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.
+#
+
+from .. import Topography
+from .Reader import ReaderBase, ChannelInfo
+
+
+class MatReader(ReaderBase):
+    _format = 'mat'
+    _name = 'MATLAB'
+    _description = '''
+Imports topography data stored in MATLAB workspace files. The reader
+automatically extracts all 2D arrays stored in the file and interprets those
+as height information. Matlab files do not store units or physical sizes.
+These need to be manually provided by the user.
+    '''
+
+    def __init__(self, fobj):
+        """
+        Reads a surface profile from a Matlab file and presents in in a
+        SurfaceTopography-conformant manner.
+
+        All two-dimensional arrays present in the matlab data file are
+        returned.
+
+        Parameters
+        ----------
+        fobj: filename or file object
+             File to read.
+        """
+        from scipy.io import loadmat
+
+        close_file = False
+        if not hasattr(fobj, 'read'):
+            fobj = open(fobj, 'rb')
+            close_file = True
+        try:
+            data = loadmat(fobj)
+            self._channels = []
+            self._height_data = []
+            for key, value in data.items():
+                is_2darray = False
+                try:
+                    nx, ny = value.shape
+                    is_2darray = True
+                except (AttributeError, ValueError):
+                    pass
+                if is_2darray:
+                    channelinfo = ChannelInfo(self,
+                                              len(self._channels),
+                                              name=key,
+                                              dim=len(value.shape),
+                                              nb_grid_pts=value.shape)
+
+                    self._channels.append(channelinfo)
+                    self._height_data.append(value)
+        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.')
+
+        return Topography(self._height_data[channel_index],
+                          physical_sizes=self._check_physical_sizes(
+                              physical_sizes),
+                          info=dict(
+                              data_source=self.channels[channel_index].name),
+                          periodic=periodic)
+
+    channels.__doc__ = ReaderBase.channels.__doc__
+    topography.__doc__ = ReaderBase.topography.__doc__