SurfaceTopography.IO package

Submodules

SurfaceTopography.IO.AL3D module

class SurfaceTopography.IO.AL3D.AL3DReader(file_path)

Bases: ReaderBase

__init__(file_path)

read_height_data(f)

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=None, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.BCR module

class SurfaceTopography.IO.BCR.BCRReader(file_path)

Bases: ReaderBase

__init__(file_path)

Load NanoSurf easyScan data files.

Parameters:: file_path (filename or file object) – File or data stream to open.

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=False, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.DATX module

class SurfaceTopography.IO.DATX.DATXReader(fobj)

Bases: ReaderBase

__init__(fobj)

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=False, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.DI module

class SurfaceTopography.IO.DI.DIReader(file_path)

Bases: ReaderBase

__init__(file_path)

Load Digital Instrument’s Nanoscope files.

Parameters:: file_path (filename or file object) – File or data stream to open.

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=False, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.DZI module

SurfaceTopography.IO.DZI.write_dzi(data: ndarray, name: str, physical_sizes: Tuple[float, float], unit: str, root_directory: str = '.', tile_size: int = 256, overlap: int = 1, format: str = 'jpg', meta_format: str = 'xml', colorbar_title=None, cmap=None, **kwargs)

Write generic numpy array to a Deep Zoom Image file. This can for example be used to create a zoomable topography with OpenSeadragon (https://openseadragon.github.io/).

Additional keyword parameters are passed to Pillow’s save function.

Parameters:

data (np.ndarray) – Two-dimensional array containing the data.
name (str) – Name of the exported file. This is used as a prefix. Output filter create the file name.xml that contains the metadata and a directory `name`_files that contains the rendered image files at different levels.
physical_sizes (tuple of floats) – Linear physical sizes of the two-dimensional array.
unit (str) – Length units of physical sizes.
root_directory (str, optional) – Root directory where to place name.xml and `name`_files. (Default: ‘.’)
tile_size (int, optional) – Size of individual tiles. (Default: 256)
overlap (int, optional) – Overlap of tiles. (Default: 1)
format (str, optional) – Data output format. Note that PNG files have seams at the boundary between tiles. Use ‘npy’ to output raw data in the native numpy format. Use ‘nc’ to output raw data as NetCDF files. (Default: ‘jpg’)
meta_format (str, optional) – Format for metadata information (the DZI file), can be ‘xml’ or ‘json’. (Default: ‘xml’)
colorbar_title (str, optional) – Additional title for the color bar that is dumped into the DZI file. Ignored if format is ‘npy’ or ‘nc’. (Default: None)
cmap (str or colormap, optional) – Color map for rendering the topography. Ignored if format is ‘npy’ or ‘nc’. (Default: None)

Returns:

manifest – List with names of files created during write operation

Return type:

list of str

SurfaceTopography.IO.DZI.write_topography_dzi(self: UniformTopographyInterface, name: str, root_directory: str = '.', tile_size: int = 256, overlap: int = 1, format: str = 'jpg', meta_format: str = 'xml', cmap=None, **kwargs)

Write topography to a Deep Zoom Image file. This can for example be used to create a zoomable topography with OpenSeadragon (https://openseadragon.github.io/).

Additional keyword parameters are passed to Pillow’s save function.

Parameters:

self (Topography) – Topogaphy to export
name (str) – Name of the exported file. This is used as a prefix. Output filter create the file name.xml that contains the metadata and a directory `name`_files that contains the rendered image files at different levels.
root_directory (str) – Root directory where to place name.xml and `name`_files.
tile_size (int, optional) – Size of individual tiles. (Default: 256)
overlap (int, optional) – Overlap of tiles. (Default: 1)
format (str, optional) – Image format. Note that PNG files have seems at the boundary between tiles. (Default: jpg)
meta_format (str, optional) – Format for metadata information (the DZI file), can be ‘xml’ or ‘json’. (Default: ‘xml’)
cmap (str or colormap, optional) – Color map for rendering the topography. (Default: None)

Returns:

filenames – List with names of files created during write operation

Return type:

list of str

SurfaceTopography.IO.DZI.generate_manifest(name: str, nb_grid_pts: Tuple[int, int], root_directory: str = '.', tile_size: int = 256, format: str = 'jpg', meta_format: str = 'xml')

Generate the file manifest, i.e. the list of files, that would be generated when writing the DZI.

Parameters:

name (str) – Name of the exported file. This is used as a prefix. Output filter create the file name.xml that contains the metadata and a directory `name`_files that contains the rendered image files at different levels.
nb_grid_pts (tuple of ints) – Number of grid points.
root_directory (str, optional) – Root directory where to place name.xml and `name`_files. (Default: ‘.’)
tile_size (int, optional) – Size of individual tiles. (Default: 256)
format (str, optional) – Data output format. Note that PNG files have seams at the boundary between tiles. Use ‘npy’ to output raw data in the native numpy format. Use ‘nc’ to output raw data as NetCDF files. (Default: ‘jpg’)
meta_format (str, optional) – Format for metadata information (the DZI file), can be ‘xml’ or ‘json’. (Default: ‘xml’)

Returns:

manifest – List with names of files created during write operation

Return type:

list of str

SurfaceTopography.IO.EZD module

class SurfaceTopography.IO.EZD.EZDReader(file_path)

Bases: ReaderBase

__init__(file_path)

Load NanoSurf easyScan data files.

Parameters:: file_path (filename or file object) – File or data stream to open.

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=False, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.FRT module

class SurfaceTopography.IO.FRT.FRTReader(file_path)

Bases: ReaderBase

__init__(file_path)

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=None, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.FromFile module

SurfaceTopography profile from file input

SurfaceTopography.IO.FromFile.binary(func)

SurfaceTopography.IO.FromFile.make_wrapped_reader(reader_func, class_name='WrappedReader', format=None, mime_types=None, file_extensions=None, name=None, description=None)

SurfaceTopography.IO.FromFile.read_hgt(fobj, *args, **kwargs)

class SurfaceTopography.IO.FromFile.HGTReader(fobj)

Bases: ReaderBase

emulates the new implementation of the readers

__init__(fobj)

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=False, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.GWY module

class SurfaceTopography.IO.GWY.GWYReader(file_path)

Bases: ReaderBase

__init__(file_path)

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=None, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.H5 module

class SurfaceTopography.IO.H5.H5Reader(fobj)

Bases: ReaderBase

__init__(fobj)

close()

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=False, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.IBW module

class SurfaceTopography.IO.IBW.IBWReader(file_path)

Bases: ReaderBase

__init__(file_path)

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=False, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.JPK module

class SurfaceTopography.IO.JPK.JPKReader(file_path)

Bases: ReaderBase

__init__(file_path)

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=None, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.LEXT module

class SurfaceTopography.IO.LEXT.LEXTReader(file_path)

Bases: ReaderBase

__init__(file_path)

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=None, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.MI module

class SurfaceTopography.IO.MI.MIReader(file_path)

Bases: ReaderBase

__init__(file_path)

process_header()

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=False, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

property info: dict: Return all the available metadata as a dict.

SurfaceTopography.IO.MI.read_header_image(header)

Reads in global metadata and information about about included channels as well as their metadata.

Parameters:: header (str) – The header as a line of text.
Returns:: mifile – Data structure item containing the metadata, with the channels as a list of ‘buffers’.
Return type:: MIFile

SurfaceTopography.IO.MI.read_header_spect(header)

Reads in metadata out of the header.

Parameters:: header (str) – The header.
Returns:: mifile – Data structure item containing the metadata.
Return type:: MIFile

class SurfaceTopography.IO.MI.Channel(name=None, unit=None, meta=None)

Bases: object

Class structure for a channel contained in the file. Has a name and metadata (height data is not needed since it is returned directly).

__init__(name=None, unit=None, meta=None)

class SurfaceTopography.IO.MI.MIFile(res=(0, 0), channels=None, meta=None)

Bases: object

Class structure for the while file. Has a list of channels, global metadata and a nb_grid_pts.

__init__(res=(0, 0), channels=None, meta=None)

SurfaceTopography.IO.Matlab module

class SurfaceTopography.IO.Matlab.MatReader(fobj)

Bases: ReaderBase

__init__(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.

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=False, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.MetroPro module

class SurfaceTopography.IO.MetroPro.MetroProReader(file_path)

Bases: ReaderBase

__init__(file_path)

read_height_data(f)

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=None, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.Mitutoyo module

class SurfaceTopography.IO.Mitutoyo.MitutoyoReader(fobj)

Bases: ReaderBase

Mitutoyo SurfTest surface roughness testers produce specifically formatted Excel spreadsheets.

__init__(fobj)

Open Excel spreadsheet produced by Mitutoyo SurfTest surface roughness testers.

The reader expects a line scan by positions and heights in columns 5 and 6 (E, F) and tries to extract standard roughness metrics from column 1 (A) on the sheet ‘DATA’. The reader expects the acquisition date in column 5 (E) row 2 on sheet ‘Certificate’.

Parameters:: fobj (filename or file object) – File to read.

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=None, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.NC module

class SurfaceTopography.IO.NC.NCReader(fobj, communicator=None)

Bases: ReaderBase

__init__(fobj, communicator=None)

close()

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=None, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

property communicator

SurfaceTopography.IO.NC.write_nc_uniform(topography, fobj, format='NETCDF3_64BIT_OFFSET')

Write topography into a NetCDF file.

Parameters:

topography (SurfaceTopography) – The topography to write to disk.
fobj (str or stream) – Name of the NetCDF file or file stream
format (str) – NetCDF file format. Default is ‘NETCDF3_64BIT_OFFSET’.

SurfaceTopography.IO.NC.write_nc_nonuniform(line_scan, fobj, format='NETCDF3_64BIT_OFFSET')

Write nonuniform line scan into a NetCDF file.

Parameters:

line_scan (SurfaceTopography) – The topography to write to disk.
fobj (str or stream) – Name of the NetCDF file or file stream
format (str) – NetCDF file format. Default is ‘NETCDF3_64BIT_OFFSET’.

SurfaceTopography.IO.NMM module

class SurfaceTopography.IO.NMM.NMMReader(fobj, rtol=1e-06)

Bases: ReaderBase

__init__(fobj, rtol=1e-06)

Initialize the NMMReader object.

Parameters:

fobj (file-like object or callable) – The file object or a callable that returns a file object to the ZIP file containing the NMM data.
rtol (float, optional) – Relative tolerance for detecting uniform grids. (Default: 1e-6).

Raises:

FileFormatMismatch – If the ZIP file does not contain exactly two files or if the files are not a DSC and a DAT file.
CorruptFile – If the number of columns in the DAT file does not match the number of entries in the DSC file or if the number of data points in the DSC file does not match the number of rows in the DAT file.

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=False, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.NMM.read_nmm(dsc_file, dat_file, rtol=1e-06)

Convenience function for reading a Nanomeasuring Machine (NMM) profile.

Parameters:

dsc_file (str or file-like object) – Path to the DSC file or file-like object.
dat_file (str or file-like object) – Path to the DAT file or file-like object.
rtol (float, optional) – Relative tolerance for detecting uniform grids. (Default: 1e-6).

SurfaceTopography.IO.NPY module

In MPI Parallelized programs:

we have to use MPI.File.Open instead of open to allow several processors to access the same file simultaneously
make the file reading in 3 steps:
- read the nb_grid_pts only (Reader.__init__)
- make the domain decomposition according to the nb_grid_pts
- load the relevant subdomain on each processor in Reader.topography()

class SurfaceTopography.IO.NPY.NPYReader(fobj, communicator=<NuMPI.MPIStub.Intracomm object>)

Bases: ReaderBase

NPY is a file format made specially for numpy arrays. They contain no extra metadata so we use directly the implementation from numpy and NuMPI.

For a description of the file format, see here: https://docs.scipy.org/doc/numpy/reference/generated/numpy.lib.format.html

__init__(fobj, communicator=<NuMPI.MPIStub.Intracomm object>)

Open file in the NPY format.

Parameters:

fobj (str) – Name of the file
communicator (mpi4py MPI communicator or NuMPI stub communicator) – MPI communicator object for parallel loads.

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=False, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.NPY.save_npy(fn, topography)

SurfaceTopography.IO.OIR module

class SurfaceTopography.IO.OIR.OirChunkType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

METADATA_LIST = 0

METADATA = 1

IMAGE = 2

DATA_BLOCK = 3

SPACER = 5

class SurfaceTopography.IO.OIR.OirMetadataBlockType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

VERSION = 1

PROPERTIES = 2

ANNOTATIONS = 3

OVERLAYS = 4

LOOKUP_TABLES = 5

TOPOGRAPHY_PREFIX = 6

DATASETS = 7

TOPOGRAPHY_UUIDS = 8

TOPOGRAPHY_PREFIX_AGAIN = 9

CAMERA = 10

LOOKUP_TABLES2 = 11

CAMERA_PREFIX = 12

CAMERA_UUIDS = 13

EVENTS = 14

class SurfaceTopography.IO.OIR.OIRReader(file_path)

Bases: DeclarativeReaderBase

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

class SurfaceTopography.IO.OIR.POIRReader(fobj)

Bases: ReaderBase

__init__(fobj)

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=None, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.OPD module

SurfaceTopography.IO.OPD.mask_undefined(data, maxval=1e+32)

If data contains undefined points, then return a masked array with all undefined points masked.

The following heuristics is applied to identify undefined points: - Remove points that are +/-inf or nan - Remove points that are >+maxval or <-maxval

class SurfaceTopography.IO.OPD.OPDReader(fobj)

Bases: ReaderBase

__init__(fobj)

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=False, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

SurfaceTopography.IO.OPDx module

class SurfaceTopography.IO.OPDx.OPDxReader(file_path)

Bases: ReaderBase

__init__(file_path)

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=False, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

info_from_manifest(prefix)

read_linescan_channel_infos(channel_index): Read line scan (profile) information

read_topography_channel_infos(channel_index): Read topography (2D map) information

class SurfaceTopography.IO.OPDx.DektakUnit(name, symbol, value, extra)

Bases: tuple

extra: Alias for field number 3

name: Alias for field number 0

symbol: Alias for field number 1

value: Alias for field number 2

SurfaceTopography.IO.OPDx.read_dimension2d_content(stream)

Reads in information about a 2d dimension.

Parameters:

stream (bytes) – The input buffer

Returns:

unit (DektakUnit) – The unit
divisor (float) – Divisor

SurfaceTopography.IO.PLU module

class SurfaceTopography.IO.PLU.PLUReader(file_path)

Bases: DeclarativeReaderBase

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

SurfaceTopography.IO.PLUX module

class SurfaceTopography.IO.PLUX.PLUXReader(file_path)

Bases: ReaderBase

__init__(file_path)

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=None, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.PS module

class SurfaceTopography.IO.PS.PSReader(file_path)

Bases: ReaderBase

__init__(file_path)

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=None, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.Reader module

class SurfaceTopography.IO.Reader.ChannelInfo(reader, index, name=None, dim=None, nb_grid_pts=None, physical_sizes=None, height_scale_factor=None, periodic=None, uniform=None, undefined_data=None, unit=None, info={}, tags={})

Bases: object

Information on topography channels contained within a file.

__init__(reader, index, name=None, dim=None, nb_grid_pts=None, physical_sizes=None, height_scale_factor=None, periodic=None, uniform=None, undefined_data=None, unit=None, info={}, tags={})

Initialize the channel. Use as much information from the file as possible by passing it in the keyword arguments. Keyword arguments can be None if the information cannot be determined. (This is the default for all keyword arguments.)

Parameters:

reader (ReaderBase) – Reader instance this channel is coming from.
index (int) – Index of channel in the file, where zero is the first channel.
name (str, optional) – Name of the channel. If no name is given, “channel <index>” will be used, where “<index>” is replaced with the index.
dim (int, optional) – Number of dimensions.
nb_grid_pts (tuple of ints, optional) – Number grid points in each dimension.
physical_sizes (tuple of floats, optional) – Physical dimensions.
height_scale_factor (float, optional) – Number by which all heights have been multiplied.
periodic (bool, optional) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
uniform (bool, optional) – Data is uniform.
has_undefined_data (bool, optional) – Underlying data has missing/undefined points.
unit (str, optional) – Length unit of measurement.
info (dict, optional) – Meta data found in the file. (Default: {})
tags (dict, optional) – Additional meta data required internally by the reader

topography(physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=False, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. The method allows to override data found in the data file.

Parameters:

physical_sizes (tuple of floats, optional) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float, optional) – Factor by which the heights should be multiplied. This parameter is only available for file formats that do not provide metadata information about units and associated length scales.
unit (str, optional) – Length unit of measurement.
info (dict, optional) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool, optional) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing)
subdomain_locations (tuple of ints, optional) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints, optional) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

property index: Unique integer channel index.

property name: Name of the channel. Can be used in a UI for identifying a channel.

property dim: 1 for line scans and 2 for topography maps.

property nb_grid_pts: Number of grid points in each direction, either 1 or 2 elements depending on the dimension of the topography.

property physical_sizes

If the physical size can be determined from the file, a tuple is returned. The tuple has 1 or 2 elements (size_x, size_y), depending on the dimension of the topography.

If the physical size can not be determined from the file, then None is returned.

Note that the physical sizes obtained from the file can be overwritten by passing a physical_sizes argument to the topography method that returns the topography object.

property height_scale_factor

If a height scale factor can be determined from the file, a float is returned.

If no height scale factor can be determined from the file, then None is returned.

Note that the height scale factor obtained from the file can be overwritten by passing a height_scale_factor argument to the topography method that returns the topography object.

property is_periodic: Return whether the topography is periodically repeated at the boundaries.

property is_uniform: Return whether the topography is uniform.

property has_undefined_data: Return whether the topography has undefined data.

property pixel_size

The pixel size is returned as the phyiscal size divided by the number of grid points. If the physical size can be determined from the file, a tuple is returned. The tuple has 1 or 2 elements (size_x, size_y), depending on the dimension of the topography.

If the physical size can not be determined from the file, then None is returned.

Note that the physical sizes obtained from the file can be overwritten by passing a physical_sizes argument to the topography method that returns the topography object. Overriding the physical size will also affect the pixel size.

property area_per_pt: The area per point is returned as the product over the pixel size tuple. If pixel_size returns None, than also area_per_pt returns None.

property unit: Length unit.

property info: dict: A dictionary containing additional information (metadata) not used by SurfaceTopography itself, but required by third-party application.

property tags: A dictionary containing additional information (metadata) used internally by the reader.

property reader

class SurfaceTopography.IO.Reader.ReaderBase

Bases: object

Base class for topography readers. These are object that allow to open a file (from filename or stream object), inspect its metadata and then request to load a topography from it. Metadata is typically extracted without reading the full file.

Readers should adhere to the following design rules: 1. Opening a file should be fast and therefore not read the whole data.

The data is read only when requesting it via the topography method.

Data corruption must be detected when opening the file. The topography method must not fail because of file corruption issues.

These rules are important to allow smooth operation of the readers in the web application TopoBank.

classmethod format(): Short string identifier for this file format. Identifier must be unique and is typically equal to the file extension of this format.

classmethod mime_types(): MIME types supported by this reader.

classmethod file_extensions(): A list of typical file extensions for this reader. Can be None if there are no typical file extensions.

classmethod name(): Short name of this file format.

classmethod description(): Long description of this file format. Should be formatted as markdown.

close()

abstract property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

property default_channel: Return the default channel. This is often the first channel with height information.

abstract topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=False, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

class SurfaceTopography.IO.Reader.CompoundLayout(structures, name=None, context_mapper=<function CompoundLayout.<lambda>>)

Bases: LayoutWithNameBase

Declare a file layout

__init__(structures, name=None, context_mapper=<function CompoundLayout.<lambda>>)

from_stream(stream_obj, context)

class SurfaceTopography.IO.Reader.If(*args, context_mapper=None)

Bases: object

Switch structure type dependent on data

__init__(*args, context_mapper=None)

name(context)

from_stream(stream_obj, context)

class SurfaceTopography.IO.Reader.Skip(size)

Bases: object

__init__(size)

from_stream(stream_obj, context)

class SurfaceTopography.IO.Reader.SizedChunk(size, structure, mode='read-once', name=None, context_mapper=None, debug=False)

Bases: LayoutWithNameBase

__init__(size, structure, mode='read-once', name=None, context_mapper=None, debug=False)

Declare a file portion of a specific size. This allows bounds checking, i.e. raising exception if too much or too little data is read.

Parameters:

size (function or int) – Function that returns the size of the chunk and takes as input the current context.
structure (structure definition) – Definition of the structure within this chunk.
mode (str) – Reading mode, can be ‘read-once’, ‘skip-missing’ or ‘loop’. ‘read-once’ and ‘skip-missing’ read the containing block once, but ‘skip-missing’ does not complain if this is not the complete chunk. ‘loop’ repeats the containing block until the full chunk has been read. (Default: ‘read-once’)
name (str) – Context name of this block. Required if mode is ‘loop’.
context_mapper (callable) – Function that takes a context and returns a new context.
debug (Bool) – Print boundary offsets of chunk. (Default: False)

from_stream(stream_obj, context)

Decode stream into dictionary.

Parameters:

stream_obj (stream-like object) – Binary stream to decode.
context (dict) – Dictionary with data that has been decoded at this point.

Returns:

decoded_data – Dictionary with decoded data entries.

Return type:

dict

class SurfaceTopography.IO.Reader.For(range, structure, name=None)

Bases: LayoutWithNameBase

Repeat structure

__init__(range, structure, name=None)

from_stream(stream_obj, context)

class SurfaceTopography.IO.Reader.While(*args, name=None)

Bases: LayoutWithNameBase

Repeat as long as condition is met

__init__(*args, name=None)

from_stream(stream_obj, context)

class SurfaceTopography.IO.Reader.DeclarativeReaderBase(file_path)

Bases: ReaderBase

Base class for automatic readers.

__init__(file_path)

property metadata

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=None, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.SUR module

class SurfaceTopography.IO.SUR.SURReader(file_path)

Bases: DeclarativeReaderBase

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

SurfaceTopography.IO.Text module

SurfaceTopography.IO.Text.write_matrix(self, fname): Saves the topography using np.savetxt. Warning: This only saves the heights; the physical_sizes is not contained in the file

SurfaceTopography.IO.VK module

class SurfaceTopography.IO.VK.VKReader(file_path)

Bases: ReaderBase

__init__(file_path)

read_vk3467_header(file_path)

read_vk34_header(f)

read_height_data(f)

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=None, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.WSXM module

class SurfaceTopography.IO.WSXM.WSXMReader(file_path)

Bases: ReaderBase

__init__(file_path)

Load WSxM data files.

Parameters:: file_path (filename or file object) – File or data stream to open.

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=False, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.X3P module

class SurfaceTopography.IO.X3P.X3PReader(file_path)

Bases: ReaderBase

__init__(file_path)

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=None, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.XYZ module

SurfaceTopography.IO.XYZ.read_text_header_hfm(fobj, unit, height_scale_factor)

Read header HFM files.

Parameters:

fobj (file object) – File object to read from.
unit (str) – Length unit of the data. Raises an error if not `None`because HFM files always give a unit.
height_scale_factor (float) – Conversion factor for the height data. Raises an error if not None because HFM files always define a height scale.

Returns:

sep (str) – Separator between columns.
usecols (list of int) – List of column indices to read.
skiprows (int) – Number of rows to skip before reading data.
unit (str) – Length unit of the data.
height_scale_factor (float) – Conversion factor for the height data.
info (dict) – Additional information.

SurfaceTopography.IO.XYZ.read_text_header_dektak(fobj, unit, height_scale_factor)

Read header of Dektak CSV files.

Parameters:

fobj (file object) – File object to read from.
unit (str) – Length unit of the data, only if not present in the file.
height_scale_factor (float) – Conversion factor for the height data, only if not present in the file.

Returns:

sep (str) – Separator between columns.
usecols (list of int) – List of column indices to read.
skiprows (int) – Number of rows to skip before reading data.
unit (str) – Length unit of the data.
height_scale_factor (float) – Conversion factor for the height data.
info (dict) – Additional information.

SurfaceTopography.IO.XYZ.read_csv(fobj, sep=None, usecols=None, skiprows=0)

Simple reader for tabular data in C(omma) S(eparated) V(alue) format. The comma should not be taken literal as the reader tries to be fuzzy (and flexible).

Parameters:

fobj (file object) – File object to read from.
sep (str, optional) – Separator between columns. (Default: White space, comma or semicolon)
usecols (list of int, optional) – List of column indices to read. (Default: All columns)
skiprows (int, optional) – Number of rows to skip before reading data. (Default: 0)

Returns:

data – List of arrays, one for each column in the file.

Return type:

list of np.ndarray

class SurfaceTopography.IO.XYZ.XYZReader(file_path)

Bases: ReaderBase

__init__(file_path)

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=None, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.ZON module

Reader for Keyence ZON files.

class SurfaceTopography.IO.ZON.ZONReader(file_path)

Bases: ReaderBase

__init__(file_path)

property channels: Returns a list of :obj:`ChannelInfo`s describing the available data channels.

topography(channel_index=None, physical_sizes=None, height_scale_factor=None, unit=None, info={}, periodic=False, subdomain_locations=None, nb_subdomain_grid_pts=None)

Returns an instance of a subclass of HeightContainer that contains the topography data. Which specific type of height container (1D, 2D, uniform, nonuniform) is returned may depend on the file content and is determined dynamically.

The returned object needs to have physical_sizes and periodicity information. If this information is not provided by the data file, then the user must specify it when calling this method. Conversely, metadata that is present in the file cannot be overridden but needs to lead to a MetadataAlreadyFixedByFile exception. The user can check if the metadata is present by inspecting the ChannelInfo of the respective data channel.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which load the default channel)
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size, then this parameter will override the physical size found in the data file.
height_scale_factor (float) – Override height scale factor found in the data file.
unit (str) – Length unit.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Whether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing).
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyFixedByFile – Raised if physical_sizes, unit or `height_scale_factor have already been defined in the file, because they should not be overridden by the user.

SurfaceTopography.IO.binary module

exception SurfaceTopography.IO.binary.ValidationError: Bases: Exception

class SurfaceTopography.IO.binary.AttrDict(*args, **kwargs)

Bases: dict

__init__(*args, **kwargs)

SurfaceTopography.IO.binary.decode(stream_obj, structure_format, byte_order='@', return_size=False, context={})

Decode a binary stream given the sequence of binary entries. Strings are stripped of zeros and white spaces.

Parameters:

stream_obj (stream-like object) – Binary stream to decode.
structure_format (list of tuples) –
List of tuples describing the sequence of entries in the binary stream. Each tuple consists of two entries

(name, format)

that give the name of the entry and the format. We support the format defined in the struct module, plus ‘u’ for UTF-8, ‘U’ for UTF-16, ‘t’ for a Pascal string with 16-bit length and ‘T’ for a Pascal string with 32-bit length. Decoder also supports per-entry endianness.
byte_order (str, optional) – Byte order (see struct.unpack). (Default: ‘@’)
return_size (bool, optional) – Return the total size the structure in addition to the decoded data. (Default: False)
context (dict, optional) – Context dictionary passed to validation and converter functions. (Default: {})

Returns:

data (dict) – Dictionary with decoded data entries.
size (int) – Size of the structure in the native binary form. (Only returned if return_size is True.)

class SurfaceTopography.IO.binary.Convert(fun, exception=None)

Bases: object

__init__(fun, exception=None)

class SurfaceTopography.IO.binary.Validate(value, exception=<class 'SurfaceTopography.IO.binary.ValidationError'>)

Bases: object

__init__(value, exception=<class 'SurfaceTopography.IO.binary.ValidationError'>)

class SurfaceTopography.IO.binary.DebugOutput(prefix='', context=False)

Bases: object

__init__(prefix='', context=False)

class SurfaceTopography.IO.binary.LayoutWithNameBase

Bases: object

Base class for file layout classes

name(context)

class SurfaceTopography.IO.binary.BinaryStructure(structure_format, byte_order='@', name=None)

Bases: LayoutWithNameBase

__init__(structure_format, byte_order='@', name=None)

Define a binary stream given the sequence of binary entries.

Parameters:

structure_format (list of tuples) –
List of tuples describing the sequence of entries in the binary stream. Each tuple consists of two entries

(name, format)

that give the name of the entry and the format. We support the format defined in the struct module, plus ‘u’ for UTF-8, ‘U’ for UTF-16, ‘t’ for a Pascal string with 16-bit length and ‘T’ for a Pascal string with 32-bit length. Decoder also supports per-entry endianness.
byte_order (str, optional) – Byte order (see struct.unpack). (Default: ‘@’)
name (str, optional) – Name of this structure. (Default: None)

from_stream(stream_obj, context)

Decode stream into dictionary.

Parameters:

stream_obj (stream-like object) – Binary stream to decode.
data (dict) – Dictionary with data that has been decoded at this point.

Returns:

decoded_data – Dictionary with decoded data entries.

Return type:

dict

class SurfaceTopography.IO.binary.BinaryArray(name, shape, dtype, conversion_fun=<function BinaryArray.<lambda>>, mask_fun=None)

Bases: object

__init__(name, shape, dtype, conversion_fun=<function BinaryArray.<lambda>>, mask_fun=None)

Defines flat binary data to be read into a numpy array.

Parameters:

name (str) – Name of the array.
shape (function or tuple) – Function that returns the shape and takes a input the current data dictionary.
dtype (function or dtype) – Function that returns the dtype and takes a input the current data dictionary.
conversion_fun (function) – Function that converts the array after reading. This can be useful for example to change the data format or transpose the array.
mask_fun (function) – Function that returns a mask with undefined data points.

name(context)

from_stream(stream_obj, context)

Skip over data block and return reader for block.

Parameters:

stream_obj (stream-like object) – Binary stream to decode.
context (dict) – Dictionary with data that has been decoded at this point.

Returns:

context – Context dictionary with file reader.

Return type:

dict

read(stream_obj, context)

Read data block into numpy array.

Parameters:

stream_obj (stream-like object) – Binary stream to decode.
context (dict) – Dictionary with data that has been decoded at this point.

Returns:

data – Nunpy array containing the data from the file.

Return type:

numpy.ndarray

class SurfaceTopography.IO.binary.RawBuffer(name, size)

Bases: object

__init__(name, size)

Defines flat binary data to be read into a numpy array.

Parameters:

name (str) – Name of the array.
size (function or int) – Function that returns the size and takes a input the current data dictionary.

name(context)

from_stream(stream_obj, context)

Skip over data block and return reader for block.

Parameters:

stream_obj (stream-like object) – Binary stream to decode.
context (dict) – Dictionary with data that has been decoded at this point.

Returns:

context – Context dictionary with file reader.

Return type:

dict

read(stream_obj, context)

Read data block into numpy array.

Parameters:

stream_obj (stream-like object) – Binary stream to decode.
context (dict) – Dictionary with data that has been decoded at this point.

Returns:

buffer – Buffer containing the raw data.

Return type:

bytes

SurfaceTopography.IO.common module

SurfaceTopography.IO.common.is_binary_stream(fobj): Check whether fobj is a binary stream

SurfaceTopography.IO.common.text(encoding='utf-8')

class SurfaceTopography.IO.common.OpenFromAny(fobj, mode='r', encoding=None)

Bases: object

Context manager for turning file names, callables that open streams or already open streams into a single stream format (binary or text with specific encoding) for subsequent reading. The file is left in an identical state, including its cursor position, when the context manager returns.

__init__(fobj, mode='r', encoding=None)

Open file

Parameters:

fobj (str or stream) – The file to be opened, specified either as a file name or a stream object.
mode (str) – Open as text (‘r’) or binary (‘rb’). (Default: None)
encoding (str) – Character encoding when opening text files. (Default: None)

Module contents

SurfaceTopography.IO.detect_format(fobj, comm=None)

Detect file format based on its content.

Parameters:

fobj (filename or file object)
comm (mpi communicator, optional)

SurfaceTopography.IO.open_topography(fobj, format=None, communicator=None)

Returns a reader object for the file fobj. The reader interface mirrors the topography interface and can be used to extract meta data (number of grid points, physical sizes, etc.) without reading the full topography in memory.

Parameters:

fobj (str or filelike object) – path of the file or filelike object
format (str, optional) – specify in which format the file should be interpreted
communicator (mpi4py or NuMPI communicator object) – MPI communicator handling inter-process communication

Returns:

Instance of a SurfaceTopography.IO.Reader.ReaderBase subclass
according to the format.

Examples

Simplest read workflow:

>>> reader = open_topography("filename")
>>> top = reader.topography()

The first topography in file is returned, independently of whether the file has multiple channels or not.

You can always check the channels and their metadata with reader.channels(). This returns a list of dicts containing attributes name, physical_sizes, nb_grid_pts, ``unit` and `height_scale_factor:

>>> reader.channels
[{'name': 'ZSensor',
  'nb_grid_pts': (256, 256),
  'physical_sizes': (9999.999999999998, 9999.999999999998),
  'unit': 'nm',
  'height_scale_factor': 0.29638271279074097},
 {'name': 'AmplitudeError',
  'nb_grid_pts': (256, 256),
  'physical_sizes': (10.0, 10.0),
  'unit': ('µm', None),
  'height_scale_factor': 0.04577566528320313}]

Here the channel ‘ZSensor’ offers a topography with sizes of 10000 nm in each dimension.

You can choose it by giving the index 0 to channel (you would use channel=1 for the second):

>>> top = reader.topography(channel=0)

The returned topography has the physical sizes found in the file.

You can also prescribe some attributes when reading the topography:

>>> top = reader.topography(channel=0, physical_sizes=(10.,10.), info={"unit":"µm"})

In order to plot the topography with matplotlib, you can use

>>> plt.pcolormesh(*top.positions_and_heights())

with origin in the lower left and correct tick labels at x and y axes, or

>>> plt.imshow(top.heights().T)

with origin in the upper left (inverted y axis).

SurfaceTopography.IO.read_topography(fn, format=None, communicator=None, **kwargs)

Returns a topography object representing the topograpgy in the file fobj. If there are multiple data channels within this file, the default channel is returned. The default channel depends on the file format; see documentation of the respective reader on this.

Parameters:

fobj (str or filelike object) – path of the file or filelike object
format (str, optional) – specify in which format the file should be interpreted
communicator (mpi4py or NuMPI communicator object) – MPI communicator handling inter-process communication
channel (int) – Number of the channel to load. See also channels method.
physical_sizes (tuple of floats) – Physical size of the topography. It is necessary to specify this if no physical size is found in the data file. If there is a physical size in the file, then specifying this parameter will raise an exception.
height_scale_factor (float) – Can be used to set height scale factor if not found in the data file.
info (dict) – This dictionary will be appended to the info dictionary returned by the reader.
periodic (bool) – Wether the SurfaceTopography should be interpreted as one period of a periodic surface. This will affect the PSD and autocorrelation calculations (windowing)
subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.
nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process.

Returns:

topography – The object containing the actual topography data.

Return type:

subclass of HeightContainer

Raises:

MetadataAlreadyDefined – Raised if given arguments for physical_sizes or height_scale_factor although it’s already given in the file.