SurfaceTopography.IO package

Submodules

SurfaceTopography.IO.AL3D module

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

Bases: ReaderBase

classmethod can_read(buffer: bytes) → MagicMatch

Check if this reader can handle a file based on magic bytes.

This method performs a fast check using the first N bytes of a file to determine if this reader can handle the format. It is used to quickly reject incompatible formats during auto-detection.

Parameters:: buffer (bytes) – First N bytes of the file (typically 512 bytes).
Returns:: YES if magic matches and this reader should work. NO if magic does NOT match and this reader should be skipped. MAYBE if cannot determine from magic alone (default).
Return type:: MagicMatch

__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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

SurfaceTopography.IO.DATX module

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

Bases: ReaderBase

classmethod can_read(buffer: bytes) → MagicMatch

Check if this reader can handle a file based on magic bytes.

This method performs a fast check using the first N bytes of a file to determine if this reader can handle the format. It is used to quickly reject incompatible formats during auto-detection.

Parameters:: buffer (bytes) – First N bytes of the file (typically 512 bytes).
Returns:: YES if magic matches and this reader should work. NO if magic does NOT match and this reader should be skipped. MAYBE if cannot determine from magic alone (default).
Return type:: MagicMatch

__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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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, channel_id=None, height_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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

SurfaceTopography.IO.FRT module

Reader for MicroProf FRT profilometry data.

The FRT format uses TLV (Tag-Length-Value) encoding: - Version 1.00: tag (uint16) + size (uint32) - Version 1.01: tag (uint16) + size (uint64)

Reference information and implementations: https://sourceforge.net/p/gwyddion/code/HEAD/tree/trunk/gwyddion/modules/file/microprof.c

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

Bases: DeclarativeReaderBase

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)

Read topography data from file.

Note: This method needs custom implementation because the data block offset must be determined by scanning through blocks.

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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

SurfaceTopography.IO.GWY module

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

Bases: ReaderBase

classmethod can_read(buffer: bytes) → MagicMatch

Check if this reader can handle a file based on magic bytes.

This method performs a fast check using the first N bytes of a file to determine if this reader can handle the format. It is used to quickly reject incompatible formats during auto-detection.

Parameters:: buffer (bytes) – First N bytes of the file (typically 512 bytes).
Returns:: YES if magic matches and this reader should work. NO if magic does NOT match and this reader should be skipped. MAYBE if cannot determine from magic alone (default).
Return type:: MagicMatch

__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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

SurfaceTopography.IO.GWY.write_gwy(self, fobj, name='Topography')

Write topography to a Gwyddion (GWY) file.

GWY is the native file format of the open-source SPM visualization and analysis software Gwyddion.

Parameters:

self (Topography) – The topography to write.
fobj (str or file-like object) – File path or file-like object to write to.
name (str, optional) – Name/title for the channel. (Default: ‘Topography’)

SurfaceTopography.IO.H5 module

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

Bases: ReaderBase

classmethod can_read(buffer: bytes) → MagicMatch

Check if this reader can handle a file based on magic bytes.

This method performs a fast check using the first N bytes of a file to determine if this reader can handle the format. It is used to quickly reject incompatible formats during auto-detection.

Parameters:: buffer (bytes) – First N bytes of the file (typically 512 bytes).
Returns:: YES if magic matches and this reader should work. NO if magic does NOT match and this reader should be skipped. MAYBE if cannot determine from magic alone (default).
Return type:: MagicMatch

__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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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, channel_id=None, height_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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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.MNT module

Reader for Digital Surf Mountains MNT files.

The MNT format is a Microsoft Compound Document File (OLE) containing: - ImagePreview: JPEG preview image - ScopedContents: Binary data with TLV-encoded metadata and zlib-compressed

ScopedResults: Parameter data
XmlHeader: UTF-16 encoded XML metadata

The ScopedContents stream uses a hierarchical TLV (Tag-Length-Value) structure: - First 8 bytes: uint64 LE size field (= stream size - 8) - Remaining bytes: TLV entries with tag (uint16 LE) + size (uint64 LE) + data

Height data container (tag 0x02BD) structure: - compressed_blocks contains multiple sections separated by uint64 size fields:

Image parameters (in Section 3, innermost tag 0x0002 container): - 0x0007: Width in pixels (uint32) - 0x0008: Height in pixels (uint32) - 0x0009: Physical size X in mm (double) - 0x000a: Physical size Y in mm (double)

Height data format: - Stored as int32 values - Data type tag (tag 0x0001 inside height_data container) indicates masking:

Height scale factor stored in pixel_scales container (typically 10 nm/count)

Note: 0xFFFF tags are used as section markers/delimiters and must be skipped when parsing nested containers.

class SurfaceTopography.IO.MNT.MNTReader(fobj)

Bases: ReaderBase

__init__(fobj)

Load Digital Surf Mountains data files.

Parameters:: fobj (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=None, 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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

SurfaceTopography.IO.NC module

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

Bases: ReaderBase

classmethod can_read(buffer: bytes) → MagicMatch

Check if this reader can handle a file based on magic bytes.

This method performs a fast check using the first N bytes of a file to determine if this reader can handle the format. It is used to quickly reject incompatible formats during auto-detection.

Parameters:: buffer (bytes) – First N bytes of the file (typically 512 bytes).
Returns:: YES if magic matches and this reader should work. NO if magic does NOT match and this reader should be skipped. MAYBE if cannot determine from magic alone (default).
Return type:: MagicMatch

__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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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.NMS module

Reader for Nanofocus NMS files.

class SurfaceTopography.IO.NMS.NMSReader(fobj)

Bases: ReaderBase

classmethod can_read(buffer: bytes) → MagicMatch

Check if this reader can handle a file based on magic bytes.

This method performs a fast check using the first N bytes of a file to determine if this reader can handle the format. It is used to quickly reject incompatible formats during auto-detection.

Parameters:: buffer (bytes) – First N bytes of the file (typically 512 bytes).
Returns:: YES if magic matches and this reader should work. NO if magic does NOT match and this reader should be skipped. MAYBE if cannot determine from magic alone (default).
Return type:: MagicMatch

__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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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

classmethod can_read(buffer: bytes) → MagicMatch

Check if this reader can handle a file based on magic bytes.

This method performs a fast check using the first N bytes of a file to determine if this reader can handle the format. It is used to quickly reject incompatible formats during auto-detection.

Parameters:: buffer (bytes) – First N bytes of the file (typically 512 bytes).
Returns:: YES if magic matches and this reader should work. NO if magic does NOT match and this reader should be skipped. MAYBE if cannot determine from magic alone (default).
Return type:: MagicMatch

__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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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

SurfaceTopography.IO.OIR module

class SurfaceTopography.IO.OIR.OirChunkType(*values)

Bases: IntEnum

METADATA_LIST = 0

METADATA = 1

IMAGE = 2

DATA_BLOCK = 3

SPACER = 5

class SurfaceTopography.IO.OIR.OirMetadataBlockType(*values)

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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

SurfaceTopography.IO.OPD module

SurfaceTopography.IO.OPD.mask_undefined(data, maxval)

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

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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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.OS3D module

Reader for Digital Metrology OmniSurf3D OS3D files.

Format documentation: https://digitalmetrology.com/omnisurf3d-file-format/

class SurfaceTopography.IO.OS3D.OS3DReader(fobj)

Bases: ReaderBase

classmethod can_read(buffer: bytes) → MagicMatch

Check if this reader can handle a file based on magic bytes.

This method performs a fast check using the first N bytes of a file to determine if this reader can handle the format. It is used to quickly reject incompatible formats during auto-detection.

Parameters:: buffer (bytes) – First N bytes of the file (typically 512 bytes).
Returns:: YES if magic matches and this reader should work. NO if magic does NOT match and this reader should be skipped. MAYBE if cannot determine from magic alone (default).
Return type:: MagicMatch

__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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

SurfaceTopography.IO.Reader module

class SurfaceTopography.IO.Reader.MagicMatch(*values)

Bases: Enum

Result of magic-based file format check.

YES = 'yes'

NO = 'no'

MAYBE = 'maybe'

class SurfaceTopography.IO.Reader.DataKind(*values)

Bases: Enum

Kind of data stored in a channel.

HEIGHT = 'height'

VOLTAGE = 'voltage'

CURRENT = 'current'

PHASE = 'phase'

AMPLITUDE = 'amplitude'

ERROR = 'error'

DEFLECTION = 'deflection'

FRICTION = 'friction'

OTHER = 'other'

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, data_kind=None, data_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, data_kind=None, data_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 (lateral dimensions).
data_kind (DataKind, optional) – Kind of data stored in this channel (HEIGHT, VOLTAGE, etc.). Defaults to HEIGHT if not specified.
data_unit (str, optional) – Unit for data values (z-axis). For height channels, this is typically the same as unit. For non-height channels, this could be ‘V’, ‘A’, ‘deg’, etc.
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 for lateral dimensions (x, y).

This is the unit for physical_sizes. For height channels, this is typically also the unit of the height data. For non-height channels, see data_unit for the unit of the data values.

property lateral_unit

Length unit for lateral dimensions (x, y).

Alias for unit property.

property data_kind

Kind of data stored in this channel.

Returns:: The kind of data (HEIGHT, VOLTAGE, CURRENT, PHASE, etc.)
Return type:: DataKind

property data_unit

Unit for data values (z-axis).

For height channels, this returns the lateral unit if no specific data unit was provided (since height is typically in the same unit as lateral dimensions). For non-height channels, this could be ‘V’, ‘A’, ‘deg’, etc.

Returns:: Unit string for the data values.
Return type:: str or None

property is_height_channel

Return whether this channel contains height data.

Returns:: True if this is a height channel, False otherwise.
Return type:: bool

property channel_id

Stable unique string identifier for this channel.

This ID is stable across different reads of the same file and does not depend on channel ordering. Format is ‘{name}’ if the name is unique, or ‘{name}#{n}’ if there are multiple channels with the same name.

Returns:: Stable channel identifier.
Return type:: str

property height_index

Index among height channels only.

This provides backwards compatibility for code that expects channels to be indexed only among height data. Non-height channels return None.

Returns:: Index among height channels, or None for non-height channels.
Return type:: int or None

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.

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.

classmethod can_read(buffer: bytes) → MagicMatch

Check if this reader can handle a file based on magic bytes.

This method performs a fast check using the first N bytes of a file to determine if this reader can handle the format. It is used to quickly reject incompatible formats during auto-detection.

Parameters:: buffer (bytes) – First N bytes of the file (typically 512 bytes).
Returns:: YES if magic matches and this reader should work. NO if magic does NOT match and this reader should be skipped. MAYBE if cannot determine from magic alone (default).
Return type:: MagicMatch

close()

height_index_to_channel_id(height_index)

Convert a height channel index to a stable channel ID.

This utility function is useful for migrating databases that stored channel references using the old height-only index system to the new stable channel_id system.

Parameters:: height_index (int) – Index among height channels (0-based).
Returns:: The stable channel_id for the height channel at that index.
Return type:: str
Raises:: ValueError – If no height channel exists at the given index.

Examples

>>> reader = open_topography("scan.ibw")
>>> # Migrate old database entry
>>> old_index = 0  # stored in database
>>> new_id = reader.height_index_to_channel_id(old_index)
>>> # Store new_id in database instead

channel_id_to_height_index(channel_id)

Convert a stable channel ID to a height channel index.

This utility function can be used to convert channel IDs back to height indices for backwards compatibility with systems that require numeric indices.

Parameters:: channel_id (str) – The stable channel identifier.
Returns:: The height index for the channel with that ID.
Return type:: int
Raises:: ValueError – If no channel with the given ID is found, or if the channel is not a height channel.

Examples

>>> reader = open_topography("scan.ibw")
>>> height_idx = reader.channel_id_to_height_index("Height")

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

property height_channels

Returns a list of :obj:`ChannelInfo`s for height channels only.

This provides backwards compatibility for code that expects only height data channels.

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

abstractmethod topography(channel_index=None, channel_id=None, height_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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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=None, comment=None)

Bases: object

Skips over bytes in a binary stream without storing them.

Use this for TLV entries or file sections that should be ignored.

Parameters:

size (int, callable, or None) – Size of the data block in bytes. Can be: - An integer for fixed size - A callable that takes context and returns size - None to read size from context[‘_block_size’] (for TLV parsing)
comment (str, optional) – Description of what is being skipped (for documentation).

__init__(size=None, comment=None)

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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

SurfaceTopography.IO.SDF module

Reader for ISO 25178-71 SDF (Surface Data File) format.

This format is defined in ISO 25178-71 and supports both ASCII and binary variants.

class SurfaceTopography.IO.SDF.SDFReader(fobj)

Bases: ReaderBase

classmethod can_read(buffer: bytes) → MagicMatch

Check if this reader can handle a file based on magic bytes.

This method performs a fast check using the first N bytes of a file to determine if this reader can handle the format. It is used to quickly reject incompatible formats during auto-detection.

Parameters:: buffer (bytes) – First N bytes of the file (typically 512 bytes).
Returns:: YES if magic matches and this reader should work. NO if magic does NOT match and this reader should be skipped. MAYBE if cannot determine from magic alone (default).
Return type:: MagicMatch

__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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

SurfaceTopography.IO.SUR module

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

Bases: DeclarativeReaderBase

classmethod can_read(buffer: bytes) → MagicMatch

Check if this reader can handle a file based on magic bytes.

This method performs a fast check using the first N bytes of a file to determine if this reader can handle the format. It is used to quickly reject incompatible formats during auto-detection.

Parameters:: buffer (bytes) – First N bytes of the file (typically 512 bytes).
Returns:: YES if magic matches and this reader should work. NO if magic does NOT match and this reader should be skipped. MAYBE if cannot determine from magic alone (default).
Return type:: MagicMatch

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

SurfaceTopography.IO.TMD module

Reader for TrueMap TMD files.

class SurfaceTopography.IO.TMD.TMDReader(file_path)

Bases: DeclarativeReaderBase

classmethod can_read(buffer: bytes) → MagicMatch

Check if this reader can handle a file based on magic bytes.

This method performs a fast check using the first N bytes of a file to determine if this reader can handle the format. It is used to quickly reject incompatible formats during auto-detection.

Parameters:: buffer (bytes) – First N bytes of the file (typically 512 bytes).
Returns:: YES if magic matches and this reader should work. NO if magic does NOT match and this reader should be skipped. MAYBE if cannot determine from magic alone (default).
Return type:: MagicMatch

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

SurfaceTopography.IO.Text module

SurfaceTopography.IO.Text.to_str(x)

class SurfaceTopography.IO.Text.AscReader(file_path)

Bases: ReaderBase

classmethod to_float(s)

parse_data(line)

parse_metadata(line)

__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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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

classmethod can_read(buffer: bytes) → MagicMatch

Check if this reader can handle a file based on magic bytes.

This method performs a fast check using the first N bytes of a file to determine if this reader can handle the format. It is used to quickly reject incompatible formats during auto-detection.

Parameters:: buffer (bytes) – First N bytes of the file (typically 512 bytes).
Returns:: YES if magic matches and this reader should work. NO if magic does NOT match and this reader should be skipped. MAYBE if cannot determine from magic alone (default).
Return type:: MagicMatch

__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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

SurfaceTopography.IO.X3P module

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

Bases: ReaderBase

classmethod can_read(buffer: bytes) → MagicMatch

Check if this reader can handle a file based on magic bytes.

This method performs a fast check using the first N bytes of a file to determine if this reader can handle the format. It is used to quickly reject incompatible formats during auto-detection.

Parameters:: buffer (bytes) – First N bytes of the file (typically 512 bytes).
Returns:: YES if magic matches and this reader should work. NO if magic does NOT match and this reader should be skipped. MAYBE if cannot determine from magic alone (default).
Return type:: MagicMatch

__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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

SurfaceTopography.IO.X3P.write_x3p(self, fobj, dtype='D', manufacturer='SurfaceTopography', model='Python Library', version=None)

Write topography to an X3P file (ISO 5436-2 / ISO 25178-72 format).

X3P is a container format conforming to the ISO 5436-2 standard for surface texture data exchange.

Parameters:

self (Topography) – The topography to write.
fobj (str or file-like object) – File path or file-like object to write to.
dtype (str, optional) – Data type for height values. Options are: - ‘D’ : 64-bit float (default) - ‘F’ : 32-bit float - ‘L’ : 32-bit unsigned integer (requires height_scale_factor) - ‘I’ : 16-bit unsigned integer (requires height_scale_factor)
manufacturer (str, optional) – Manufacturer name to include in metadata. (Default: ‘SurfaceTopography’)
model (str, optional) – Model/software name. (Default: ‘Python Library’)
version (str, optional) – Version string. If None, uses the SurfaceTopography version.

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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

SurfaceTopography.IO.ZMG module

Reader for KLA Zeta ZMG files.

class SurfaceTopography.IO.ZMG.ZMGReader(file_path)

Bases: DeclarativeReaderBase

classmethod can_read(buffer: bytes) → MagicMatch

Check if this reader can handle a file based on magic bytes.

This method performs a fast check using the first N bytes of a file to determine if this reader can handle the format. It is used to quickly reject incompatible formats during auto-detection.

Parameters:: buffer (bytes) – First N bytes of the file (typically 512 bytes).
Returns:: YES if magic matches and this reader should work. NO if magic does NOT match and this reader should be skipped. MAYBE if cannot determine from magic alone (default).
Return type:: MagicMatch

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

SurfaceTopography.IO.ZON module

Reader for Keyence ZON files.

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

Bases: ReaderBase

__init__(file_path)

open(z, fn)

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.

There are three ways to specify which channel to load: 1. channel_index: Index into the full channels list (all data types) 2. channel_id: Stable string identifier (e.g., “Height”, “Phase#2”) 3. height_channel_index: Index among height channels only (backwards

Only one of these parameters should be specified. If none are given, the default channel is loaded.

Parameters:

channel_index (int) – Index of the channel to load. See also channels method. (Default: None, which loads the default channel)
channel_id (str) – Stable channel identifier string. This is the recommended way to identify channels for storage in databases as it remains stable even if channel ordering changes.
height_channel_index (int) – Index among height channels only. This provides backwards compatibility for databases that stored channel indices before non-height channels were supported.
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.
ValueError – Raised if more than one channel selection parameter is provided, or if the specified channel cannot be found.

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=None, lazy=True)

Bases: object

__init__(name, size=None, lazy=True)

Defines a raw binary data block.

Parameters:

name (str) – Name of the data block.
size (int, callable, or None) – Size of the data block in bytes. Can be: - An integer for fixed size - A callable that takes context and returns size - None to read size from context[‘_block_size’] (for TLV parsing)
lazy (bool, optional) – If True, return a ReaderProxy for deferred reading. If False, read data immediately. Default: True.

name(context)

from_stream(stream_obj, context)

Read or skip over data block.

Parameters:

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

Returns:

Dictionary with the data or a reader proxy.

Return type:

dict

read(stream_obj, context)

Read data block.

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

class SurfaceTopography.IO.binary.TextBuffer(name, size=None, encoding='ascii')

Bases: LayoutWithNameBase

Reads a text block from a binary stream.

Parameters:

name (str) – Name of the text entry.
size (int, callable, or None) – Size of the text block in bytes. Can be: - An integer for fixed size - A callable that takes context and returns size - None to read size from context[‘_block_size’] (for TLV parsing)
encoding (str, optional) – Text encoding. Default: ‘ascii’.

__init__(name, size=None, encoding='ascii')

name(context)

from_stream(stream_obj, context)

class SurfaceTopography.IO.binary.TLVContainer(tag_map, name=None, tag_format='<H', size_format='<Q', count=None, container_size=None, store_by_name=True, entry_prefix_format=None)

Bases: LayoutWithNameBase

Reads TLV (Tag-Length-Value) encoded blocks from a binary stream.

TLV format: - Tag: identifies the block type (uint16 by default) - Length: size of the data section - Value: the actual data

Parameters:

tag_map (dict) – Maps tag IDs to layout classes. Each layout class must have a from_stream(stream_obj, context) method. Special values: - None or missing: store raw bytes - ‘text’: treat as ASCII text - Layout class instance: use that layout to parse
name (str, optional) – Name for this container in the result dict. Default: None.
tag_format (str, optional) – Format for tag field. Default: ‘<H’ (uint16 LE).
size_format (str, optional) – Format for size field. Default: ‘<Q’ (uint64 LE). Use ‘<I’ for uint32.
count (int or callable, optional) – Number of TLV entries to read. If None, reads until end of container (requires knowing the container size). Default: None.
container_size (int or callable, optional) – Total size of the container in bytes. Used when count is None to determine when to stop reading. Default: None.
store_by_name (bool, optional) – If True, also store entries by their layout’s name (if available) in addition to by tag ID. Default: True.
entry_prefix_format (str, optional) – Format for a prefix field before each TLV entry. If set, this many bytes are read and skipped before each entry. Used for structures where each TLV entry is preceded by a size hint. Default: None (no prefix).

__init__(tag_map, name=None, tag_format='<H', size_format='<Q', count=None, container_size=None, store_by_name=True, entry_prefix_format=None)

name(context)

from_stream(stream_obj, context)

Parse TLV entries from stream.

Parameters:

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

Returns:

Dictionary with parsed entries keyed by tag ID.

Return type:

dict

class SurfaceTopography.IO.binary.LayoutWithTrailingData(name, fields)

Bases: LayoutWithNameBase

Layout that parses structured fields then stores remaining bytes as raw data.

This is useful for TLV blocks that have a known header structure followed by variable-length data (e.g., compressed data blocks).

Parameters:

name (str) – Name for this block in the result dict.
fields (list) – Field definitions for the header. Can include: - Tuples: (name, format) following struct module conventions - Layout classes: Objects with from_stream() method (like For)

__init__(name, fields)

from_stream(stream_obj, context)

class SurfaceTopography.IO.binary.ZlibBlockChain(name, prefix_format='<QII', min_decompressed_size=1000)

Bases: LayoutWithNameBase

Reads a chain of sequential zlib-compressed blocks from a binary stream.

This class is designed for file formats like MNT that store height data as a series of zlib-compressed blocks with a fixed prefix structure. The blocks are stored sequentially in memory and can be chained together using the compressed_size field in each prefix.

Block structure: ` [prefix][zlib data][prefix][zlib data]... `

Default prefix format (16 bytes): - Bytes 0-7: uint64 LE - element_offset (for logical ordering) - Bytes 8-11: uint32 LE - elements_per_block - Bytes 12-15: uint32 LE - compressed_size

The class scans for the first zlib block by looking for the zlib magic byte (0x78), then chains through all subsequent blocks using the compressed_size field.

Parameters:

name (str) – Name for the parsed result in the context dictionary.
prefix_format (str, optional) – Struct format for the block prefix. Default: ‘<QII’ (uint64 + 2*uint32). The last field must be the compressed_size.
min_decompressed_size (int, optional) – Minimum decompressed size to consider a valid block. This filters out false positive zlib matches. Default: 1000.

Examples

>>> layout = ZlibBlockChain('height_blocks')
>>> result = layout.from_stream(stream, {})
>>> blocks = result['height_blocks']
>>> for block in blocks:
...     elem_offset = block['elem_offset']
...     data = block['data']  # decompressed bytes

ZLIB_COMPRESSION_LEVELS = [1, 94, 156, 218]

__init__(name, prefix_format='<QII', min_decompressed_size=1000)

from_stream(stream_obj, context)

Parse zlib-compressed blocks from stream.

Parameters:

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

Returns:

Dictionary with {name: list of block dicts}, where each block dict contains ‘elem_offset’, ‘elem_per_block’, and ‘data’ keys.

Return type:

dict

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.