5.4. DataObjectIO#

Summary:	import or export dataObject from/to several file formats.
Type:	Algorithm
License:	Licensed under LGPL.
Platforms:	Windows, Linux
Author:	W. Lyda, M. Gronle, ITO, Universität Stuttgart

5.4.1. Overview#

This filter contains two different export- / import-functionalities for dataObjects, image or raw.

Image-export functions converts dataObjects to image data and saves them as common image-formats.

uint8 or uint16 are saved as gray-values (8bit or if supported as 16bit) or if the image format allows color are saved according to the defined color palette.
float32 or float64 are saved as gray-values (8bit or if supported as 16bit) or according to the defined color palette. Therefore the values must be between 0.0 and 1.0. Values outside these borders are clipped. If the image format supports RGBA, invalid values are saved as transparent values (alpha=zero) else as black values.
rgba32 can be saved as ‘rgb’ (full opacity), ‘rgba’ (alpha channel is considered, not supported by all formats) or gray formats, where the color image is transformed to gray. if a format from a color palette is indicated, the color image is transformed to gray first and then interpreted using the indicated color palette.

Basic export-filter definition: source object, filename, palette, … Basic import-filter definition: destination object, filename, channel-specification, …

Raw-export functions write/read the data to/from txt-based or binary file formats.

These algorithms are defined in the plugin:

send_message(sender, recipient, message_body[, priority=1])#

Send a message to a recipient

Parameters:

sender (str) – The person sending the message
recipient (str) – The recipient of the message
message_body (str) – The body of the message
priority (int or None) – The priority of the message, can be a number 1-5

Returns:

the message id

Return type:

int

Raises:

ValueError – if the message_body exceeds 160 characters
TypeError – if the message_body is not a basestring

5.4.2. Details#

Detailed overview about all defined algorithms:

itom.algorithms.loadAnyImage(destinationImage, filename[, colorElement])#

load the following image formats from a file to a 2D data object:

png: 8bit/16bit, color available, transparency available
tiff/tif: 8bit/16bit, color available
jpg: 8bit, color available
jp2: 8bit/16bit, color available
ras/sr: 8bit, color available
ppm: 8bit, color available
pgm: 8bit/16bit
pbm: 8bit, color available
bmp/dip: 8bit, color available
gif: 8bit, color available, transparency available
xbm: 8bit, color available, transparency available (X BitMap)
xpm: 8bit, color available, transparency available (X PixMap)

The file format only provides color or transparency data if indicated above.

You can choose which channel (colorElement) of the loaded file should be used for the data object. asIs loads the file as it is: monochrome formats are loaded as uint8 or uint16 data object, while colored file formats are loaded as rgba32 data object. The color elements alpha, R, G, B, RGB, RGBA are only available for colored file formats are only load the selected channels to either a uint8/uint16 data object or a rgba32 data object (rgb and rgba only). GRAY converts a colored file format to grayscale before loading it to an uint8 or uint16 data object.

All file formats are loaded using OpenCV, besides gif, xbm, xpm which are loaded via Qt.

Parameters:

destinationImage (itom.dataObject) – DataObject that will be filled with the loaded file content
filename (str) – Source file name
colorElement (str, optional) –
Color element: asIs (default) | alpha | R | G | B | RGB | ARGB | GRAY; ‘asIs’ ignores alpha channel from supported file types (use rgba instead).

Match: [“asIs”, “alpha”, “R”, “G”, “B”, “RGB”, “RGBA”, “GRAY”], Default: “asIs”

itom.algorithms.loadAvantesRaw(destinationObject, filename[, dataType])#

load binary files from Avantes devices. The destinationObject is a RxN float32 data object, where R is the number of spectas in the file and N the number of pixels. Use the optional parameter ‘dataType’ to decide which type of data should be loaded (including the calibration wavelength table of the grating).

The description of the file format has been taken from ‘AvaSoft 8 File Formats.pdf’

Parameters:

destinationObject (itom.dataObject) – Destination dataObject
filename (str) – Source filename
dataType (int, optional) –
type of data to be loaded: 0 fully calculated array of wavelengths, 1 scopemode spectrum, 2 dark spectrum, 3 reference spectrum

Value range: [0, 3], Default: 1

itom.algorithms.loadDataObject(destinationImage, filename[, colorElement])#

loads a 2D data object from image formats via QImage (*.gif *.xbm *.xpm). This filter is deprecated and can also be directly used via the filter ‘loadAnyImage’

Parameters:

destinationImage (itom.dataObject) – Empty dataObjet
filename (str) – Source file name
colorElement (str, optional) –
Color element: asIs (default) | alpha | R | G | B | RGB | ARGB | GRAY; ‘asIs’ ignores alpha channel from supported file types (use rgba instead).

Match: [“asIs”, “alpha”, “R”, “G”, “B”, “RGB”, “RGBA”, “GRAY”], Default: “asIs”

itom.algorithms.loadFRT(destinationObject, filename[, xyUnit, valueUnit, bufferType, sensorCounter, printAllBufferTypes])#

Loads MicroProf FRT data from profilometers (based on FRT File Format specification 4.0.1.0).

The files are loaded in a unit16, int32 or float64 data format. The FRT file format provides further information about the measurement conditions and system settings. Several of these settings are saved in tags of the resulting dataObject. These are among others (if available):

comment: optional multiline comment of the file
scanDirection: string with the scan direction for the data acquisition
measureRange: total measurement range
startTime: start time of measurement (seconds from 1970)
duration: duration of measurement in seconds
zTableType: string with the type of the used z-scanning stage
xyTableType: string with the type of the used xy-scanning stage
hardware: name of the measurement device (str)
speedX: speed of the x-stage in m/s (only given if overrideSpeed is false)
speedY: speed of the y-stage in m/s (only given if overrideSpeed is false)
sensorDelay: wait at each point so many ms (only given if overrideSpeed is true)
checkSensorError: during measurement check the error state of the sensor
sensorErrorTime: wait max. so many ms for non-error state of the sensor
scanBackMeas: during scan: measure when scanning back
title: name of dataset if given
heatingChamber: temperature of heating chamber if given
xyStitchingActive : ‘true’ if xy stitching was active, else ‘false’
xyStitchingResolutionDivisor : only given if xyStitchingActive is ‘true’

Some frt files can contain more than one dataset. Multiple datasets can represent different types (topology, intensity, phases…), they can come from different sensors (e.g. upside and downside sensor) or they can be acquired at different levels. Per default, the standard dataset (e.g. topology) is loaded. Set ‘printAllBufferTypes’ to 1 in order to get a list of available buffers printed to the command line (only if more than one buffer is available). While buffers at different levels are automatically loaded to a 3D data object instead of a 2D one, the user can select the type and sensor counter that should be loaded. Possible values are among others:

bufferType

0x0001: piezo
0x0002: intensity
0x0004: topography
0x0008: re_part
0x0010: im_part
0x0040: camera
0x0080: thickness
0x0100: dibfromfile
0x0200: abs_val
0x0400: phase
0x0800: samplethickness
0x1000: afm
0x0200: quality
0x0401: fit
0x0402: slope

sensorCounter

Currently, only 0 (sensor 1 - top) and 1 (sensor 2 - bottom) seems to be implemented in files. In future sensor 3 and sensor 4 (indices 2 and 3) might follow.

Parameters:

destinationObject (itom.dataObject) – Destination dataObject
filename (str) – Source filename
xyUnit (str, optional) –
Unit of x and y axes. Nist or BCR sdf files assumes to have m as default unit, this can be scaled using other values than m. Default: m (Be careful that other units than ‘m’ lead to a multiplication of all values that might exceed the data type limit.)

Match: [“m”, “cm”, “mm”, “Âµm”, “nm”], Default: “mm”
valueUnit (str, optional) –
Unit of value axis. x3p assumes to have m as default unit, this can be scaled using other values than m. Default: m (Be careful that other units than ‘m’ lead to a multiplication of all values that might exceed the data type limit.)

Match: [“m”, “cm”, “mm”, “Âµm”, “nm”], Default: “mm”
bufferType (int, optional) –
some files contain more than one dataset. Then pass the bufferType here (its mask is 0x0000ffdf), if 0 is given, the default buffer type is used.

Value range: [0, 65503], Default: 0
sensorCounter (int, optional) –
some files contain more than one dataset. Its type is selected by ‘bufferType’. Sometimes the result can come from different sensors, then select the sensor index here.

Value range: [0, 3], Default: 0
printAllBufferTypes (int, optional) –
If 1 and different buffer types are available, they are printed to the command line.

Value range: [0, 1], Default: 0

itom.algorithms.loadIDO(destinationObject, filename)#

Tries to load the given ido or idh-file as itom dataObject. Data in the given file must have been saved using saveIDO in a xml-compatible file format, whereas *.idh only contains meta information of a data object and *.ido contains the full object.

Parameters:

destinationObject (itom.dataObject) – DataObject that will be filled with the loaded file content
filename (str) – Source file name

itom.algorithms.loadKeyenceVk4(destinationObject, filename[, setname, xyUnit, valueUnit])#

This filter loads Keyence VK4 profilometry images from Keyence devices (e.g. laser scanning microscope).

Parameters:

destinationObject (itom.dataObject) – Destination dataObject
filename (str) – Source filename
setname (str, optional) –
name of data set to load, empty string prints a list of all available dataset names. Possible values are: topo0, topo1, …, intensity0, intensity1, …, peak, color

Match: [“topo0”, “topo1”, “topo2”, “intensity0”, “intensity1”, “intensity2”, “peak”, “color”], Default: “topo0”
xyUnit (str, optional) –
Unit of x and y axes. VK4 assumes to have m as default unit, this can be scaled using other values than m. Default: mm.

Match: [“mm”, “cm”, “mm”, “Âµm”, “nm”], Default: “m”
valueUnit (str, optional) –
Unit of value axis (only valid for topography data channels). VK4 assumes to have m as default unit, this can be scaled using other values than m. Default: mm.

Match: [“mm”, “cm”, “mm”, “Âµm”, “nm”], Default: “m”

itom.algorithms.loadNanoscopeIII(destinationObject, filename[, numberOfImage])#

This filter loads NanoscopeIII data from Veeco devices. This filter was tested with files from an AFM device ‘Dimension3100’ using the file format 0x05310001. If a file of a other version is used no guarantee about scaling can be given.If a file of Version 4.3 is loaded, no information about the value units are available.

Parameters:

destinationObject (itom.dataObject) – Empty dataObject where the image will be saved to. The destinationObject will be of type float32.
filename (str) – Absolute or relative path to the Veeco nanoscope file (suffix 001, 002, 003, …).
numberOfImage (int, optional) –
defines the index of the image which will be loaded (default: 0). If the parameter is set to -1 a list of all images included in the file will be printed.

Value range: [-1, inf], Default: 0

itom.algorithms.loadSDF(destinationObject, filename[, xyUnit, valueUnit, nanValue])#

loads an ascii or binary-based surface data file to a 1D or 2D data object (sdf), versions aNIST-1.0, aISO-1.0, bISO-1.0 (ISO 25178-71) or aBCR-1.0 (e.g. Zygo export format) are supported.

Parameters:

destinationObject (itom.dataObject) – data object where the file data is loaded to. The type of destinationObject corresponds to the type of the data block in the sdf file (uint8, uint16, uint32, int8, int16, int32, float32, float64) or always float64 if the header value Zscale is != 1.0 or the valueUnit is != ‘m’
filename (str) – filename of the sdf file (aISO-1.0, aNIST-1.0, aBCR-1.0 or bISO-1.0 format)
xyUnit (str, optional) –
Unit of x and y axes. Nist or BCR sdf files assumes to have m as default unit, this can be scaled using other values than m. Default: m (Be careful that other units than ‘m’ lead to a multiplication of all values that might exceed the data type limit.)

Match: [“m”, “cm”, “mm”, “Âµm”, “nm”], Default: “mm”
valueUnit (str, optional) –
Unit of value axis. x3p assumes to have m as default unit, this can be scaled using other values than m. Default: m (Be careful that other units than ‘m’ lead to a multiplication of all values that might exceed the data type limit.)

Match: [“m”, “cm”, “mm”, “Âµm”, “nm”], Default: “mm”
nanValue (str, optional) – If this string occurs in the data block, the value will be replaced by NaN if float32 or float64 as output format. If ‘<minrange>’ or <maxrange> the minimum or maximum value of the data type in the data block is assumed (e.g. <maxrange> is used by Zygo to describe NaN values). MountainsMap writes ‘BAD’ as invalid value (following ISO25178-71). This value is ignored for binary input since invalid values are directly encoded in floating point values.

itom.algorithms.loadTXT(destinationObject, filename[, ignoreLines, asMatrix, separatorSign, decimalSign, wrapSign, encoding])#

loads an ascii-based data file like txt, csv, tsv or space separated values.

The text file is loaded line by line and tried to be interpreted as an array. It is possible to ignore the first n lines (optional parameter ignoreLines). The full content of these ignored lines is then saved in the tag ‘ignoredLines’ of the destinationObject.

Parameters:

destinationObject (itom.dataObject) – Empty dataObject
filename (str) – Source file name
ignoreLines (int, optional) –
Ignore the first n-lines.

Value range: [0, inf], Default: 0
asMatrix (int, optional) –
1. Try to interpret list elements with 3 elements per row as a matrix or (0) load as written.
Value range: [0, 1], Default: 0
separatorSign (str, optional) – Uses this as the separator between elements. If NULL, try to guess.
decimalSign (str, optional) –
Uses this as the sign for decimal numbers. If <guess>, try to guess if the decimal sign is a dot (.) or comma (,).

Match: [“<guess>”, “.”, “,”], Default: “<guess>”
wrapSign (str, optional) – Sometimes numbers are wrapped by a sign (.e.g ‘2.3’ or “4.5”). If so, indicate the character(s) that wrap the numbers.
encoding (str, optional) – encoding of text file, e.g. UTF-8, UTF-16, ISO 8859-1… Default: empty string -> the encoding is guessed due to a auto-detection of the first 64 bytes in the text file (using the BOM (Byte Order Mark)).

itom.algorithms.loadZygoMetroPro(destinationObject, filename[, topography, xyUnit, valueUnit])#

load binary MetroPro files from Zygo. This import filter is mainly tested with the first generation of MetroPro files. However, newer files should also be loaded with the limitation, that only the tags from the first generation are saved into the ‘destinationObject’.

Per default, a topography is loaded from the binary file into a float32 dataObject. If available, the optional parameter ‘topography’ can be set to 0 in order to load the intensity data to a uint16 dataObject. The ‘destinationObject’ contains many tags that are directly obtained from the binary files.

Use the optional parameters ‘xyUnit’ and ‘valueUnit’ to get the result in a desired unit. ‘valueUnit’ is ignored for intensity data.

The file format has been implemented based on the MetroPro Reference Guide, version OMP-0347K.

Parameters:

destinationObject (itom.dataObject) – Destination dataObject
filename (str) – Source filename
topography (int, optional) –
load topography data (1, default), else intensity data (0)

Value range: [0, 1], Default: 1
xyUnit (str, optional) –
Unit of x and y axes. MetroPro assumes to have m as default unit, this can be scaled using other values than m. Default: mm.

Match: [“mm”, “cm”, “mm”, “Âµm”, “nm”], Default: “m”
valueUnit (str, optional) –
Unit of value axis. MetroPro assumes to have m as default unit, this can be scaled using other values than m. Default: mm.

Match: [“mm”, “cm”, “mm”, “Âµm”, “nm”], Default: “m”

itom.algorithms.saveBMP(sourceImage, filename, palette)#

Saves a real, 2D dataObject as bmp-file or dip-file (bitmap, 8bit only).

The following conventions hold for saving the image:

fixed-point data types (uint8, uint16, uint32, int8, int16, int32) will be scaled to the supported 8bit range [0,255] and saved using the given color palette
float32 or float64 data types are scaled from [0.0, 1.0] to the supported 8bit range [0,255] and saved using the given color palette. Values outside of [0.0, 1.0] are clipped to the boundary value. Invalid values are saved as transparent values (alpha = 0).
rgba32 data type are saved depending on the given color palette. They can be saved as colored image without transparency (‘rgb’) or with considering the alpha channel as transparent values (‘rgba’). If another color palette than ‘rgb’ or ‘rgba’ is indicated, the object is at first transformed to gray and than handled as uint8 or uint16 data type.

The following base color palettes exist (further, user-defined palettes can be used, too):

gray: [0,255] gray-values, 8bit
rgba: color with transparency (converted to gray-levels however), 8bit (rgba32 input only)
rgb: color without transparency, 8bit (rgba32 input only)
grayMarked: [0,255], gray-values, 0: violet, 255: red, 8bit
falseColor, falseColorIR: [0,255], (inverse) false colors, 8bit
hotIron: [0,255], hot iron map, 8bit
red: [0,255], from black to red, 8bit
green: [0,255], from black to green, 8bit
blue: [0,255], from black to blue, 8bit

This filters uses OpenCV to save the image.

Parameters:

sourceImage (itom.dataObject) – Real, 2D data object
filename (str) – Destination filename
palette (str) – Color palette name [gray, rgb, <any-name-of-a-color-palette>, …]

itom.algorithms.saveDataObject(sourceImage, filename, format, bitscaling[, lowLimit, highLimit, colorFormat])#

saves 1D and 2D dataObject to image formats via QImage (for saving images it is recommended to use the specific saveABC (savePNG, saveGIF, saveBMP…) commands).

Parameters:

sourceImage (itom.dataObject) – 2D-DataObject of anytype or 3-planes DataObject of uint8
filename (str) – Destination filename
format (str) – Format of the Image according to QImage: [‘QImage::Format_Mono’, ‘QImage::Format_MonoLSB’, ‘QImage::Format_Indexed8’, ‘QImage::Format_RGB32’, ‘QImage::Format_ARGB32’
bitscaling (int) –
Toggle bit-scaling, 0 = off, 1 = autoscale (default), 2 = userdefined ranges

Value range: [0, 2], Default: 1
lowLimit (float, optional) –
Lowest limit. Will become 0

All values allowed, Default: 0
highLimit (float, optional) –
Lowest limit. Will become max<bitdepth>

All values allowed, Default: 1
colorFormat (str, optional) – When DataObject of type float32, their format should be –>Gray<– or –>RGB<–

itom.algorithms.saveIDO(sourceObject, filename[, headerOnly, tags2Binary])#

The given dataObject of any size and data format is saved in an itom-specific xml-file (suffix: ido, idh).

It is possible to define if only meta information (tags, scaling, offset…) should be saved in the xml-file (suffix: idh, itom data header) or if the array and meta information should be saved (suffix: ido, itom data object). Data is always saved in a base64-encoded format while the header text is mostly written in plain, ascii text. Using this filter, the data object including all its meta information is saved and can be reload using loadIDO.

Parameters:

sourceObject (itom.dataObject) – Any type of dataObject
filename (str) – Destination filename
headerOnly (int, optional) –
If 0 the complete dataObject is saved (data + metadata) [default], else the filter saves only metadata

Value range: [0, 1], Default: 0
tags2Binary (int, optional) –
If 0 meta information are saved as clear text, else double tags are saved as binary

Value range: [0, 1], Default: 0

itom.algorithms.saveJPG(sourceImage, filename, palette[, compression])#

Saves a real, 2D dataObject as jpg-file or jp2-file (only jp2 supports 16bit but is not much known).

The following conventions hold for saving the image:

fixed-point data types (uint8, uint16, uint32, int8, int16, int32) will be scaled to the supported 8bit range [0,255] and saved using the given color palette
float32 or float64 data types are scaled from [0.0, 1.0] to the supported 8bit range [0,255] and saved using the given color palette. Values outside of [0.0, 1.0] are clipped to the boundary value. Invalid values are saved as transparent values (alpha = 0).
rgba32 data type are saved depending on the given color palette. They can be saved as colored image without transparency (‘rgb’) or with considering the alpha channel as transparent values (‘rgba’). If another color palette than ‘rgb’ or ‘rgba’ is indicated, the object is at first transformed to gray and than handled as uint8 or uint16 data type.

The following base color palettes exist (further, user-defined palettes can be used, too):

gray: [0,255] gray-values, 8bit
rgba: color with transparency (converted to gray-levels however), 8bit (rgba32 input only)
rgb: color without transparency, 8bit (rgba32 input only)
grayMarked: [0,255], gray-values, 0: violet, 255: red, 8bit
falseColor, falseColorIR: [0,255], (inverse) false colors, 8bit
hotIron: [0,255], hot iron map, 8bit
red: [0,255], from black to red, 8bit
green: [0,255], from black to green, 8bit
blue: [0,255], from black to blue, 8bit

This filters uses OpenCV to save the image.

Parameters:

sourceImage (itom.dataObject) – Real, 2D data object
filename (str) – Destination filename
palette (str) – Color palette name [gray, gray16, rgb, rgba, <any-name-of-a-color-palette>]. ‘gray16’ supported for ‘.jp2’ only
compression (int, optional) –
Compression rate, 0: high, 100: low

Value range: [0, 100], Default: 90

itom.algorithms.savePGM(sourceImage, filename, palette[, binaryOut])#

Saves a real, 2D dataObject as pgm-file or pbm-file (portable gray map or portable bit map, 16bit only for pgm-format).

The following conventions hold for saving the image:

fixed-point data types (uint8, uint16, uint32, int8, int16, int32) will be scaled to the supported 8bit range [0,255] or 16bit range [0, 65535] and saved using the given color palette (only gray-valued maps are allowed)
float32 or float64 data types are scaled from [0.0, 1.0] to the supported 8bit range [0,255] or 16bit range [0, 65535] and saved using the given color palette. Values outside of [0.0, 1.0] are clipped to the boundary value. Invalid values are saved as transparent values (alpha = 0).
rgba32 data type are saved depending on the given color palette. The object is at first transformed to gray and than handled as uint8 or uint16 data type. Coloured images are not supported by this format.

The following base color palettes are supported:

gray: [0,255] gray-values, 8bit
gray16: [0,65535] gray-values, 16bit

This filters uses OpenCV to save the image.

Parameters:

sourceImage (itom.dataObject) – Real, 2D data object
filename (str) – Destination filename
palette (str) – Color palette name [gray, gray16]
binaryOut (int, optional) –
Enable binary coding

Value range: [0, 1], Default: 1

itom.algorithms.savePNG(sourceImage, filename, palette[, compression, addAlphaChannel])#

Saves a real, 2D dataObject as png-file (portable network graphic).

The following conventions hold for saving the image:

fixed-point data types (uint8, uint16, uint32, int8, int16, int32) will be scaled to the supported 8bit range [0,255] or 16bit range [0, 65535] and saved using the given color palette
float32 or float64 data types are scaled from [0.0, 1.0] to the supported 8bit range [0,255] or 16bit range [0, 65535] and saved using the given color palette. Values outside of [0.0, 1.0] are clipped to the boundary value. Invalid values are saved as transparent values (alpha = 0).
rgba32 data type are saved depending on the given color palette. They can be saved as colored image without transparency (‘rgb’) or with considering the alpha channel as transparent values (‘rgba’). If another color palette than ‘rgb’ or ‘rgba’ is indicated, the object is at first transformed to gray and than handled as uint8 or uint16 data type.

The following base color palettes exist (further, user-defined palettes can be used, too):

gray: [0,255] gray-values, 8bit
gray16: [0,65535] gray-values, 16bit
rgba: color with transparency, 8bit (rgba32 input only)
rgb: color without transparency, 8bit (rgba32 input only)
grayMarked: [0,255], gray-values, 0: violet, 255: red, 8bit
falseColor, falseColorIR: [0,255], (inverse) false colors, 8bit
hotIron: [0,255], hot iron map, 8bit
red: [0,255], from black to red, 8bit
green: [0,255], from black to green, 8bit
blue: [0,255], from black to blue, 8bit

This filters uses OpenCV to save the image.

Parameters:

sourceImage (itom.dataObject) – Real, 2D data object
filename (str) – Destination filename
palette (str) – Color palette name [gray, gray16, rgba, rgb, <any-name-of-a-color-palette>].
compression (int, optional) –
Compression rate, 0: high, 9: low

Value range: [0, 9], Default: 9
addAlphaChannel (int, optional) –
If enabled and in case of floating point values, invalid values will we transparent (alpha=0), else full opacity.

Value range: [0, 1], Default: 1

itom.algorithms.savePPM(sourceImage, filename, palette[, binaryOut])#

Saves a real, 2D dataObject as ppm-file (portable pixel map, 8bit only).

The following conventions hold for saving the image:

fixed-point data types (uint8, uint16, uint32, int8, int16, int32) will be scaled to the supported 8bit range [0,255] and saved using the given color palette
float32 or float64 data types are scaled from [0.0, 1.0] to the supported 8bit range [0,255] and saved using the given color palette. Values outside of [0.0, 1.0] are clipped to the boundary value. Invalid values are saved as transparent values (alpha = 0).
rgba32 data type are saved depending on the given color palette. They can be saved as colored image without transparency (‘rgb’) or with considering the alpha channel as transparent values (‘rgba’). If another color palette than ‘rgb’ or ‘rgba’ is indicated, the object is at first transformed to gray and than handled as uint8 or uint16 data type.

The following base color palettes exist (further, user-defined palettes can be used, too):

gray: [0,255] gray-values, 8bit
rgba: color with transparency (converted to gray-levels however), 8bit (rgba32 input only)
rgb: color without transparency, 8bit (rgba32 input only)
grayMarked: [0,255], gray-values, 0: violet, 255: red, 8bit
falseColor, falseColorIR: [0,255], (inverse) false colors, 8bit
hotIron: [0,255], hot iron map, 8bit
red: [0,255], from black to red, 8bit
green: [0,255], from black to green, 8bit
blue: [0,255], from black to blue, 8bit

This filters uses OpenCV to save the image.

Parameters:

sourceImage (itom.dataObject) – Real, 2D data object
filename (str) – Destination filename
palette (str) – Color palette name [gray, <any-name-of-a-color-palette>, …]
binaryOut (int, optional) –
Enable binary coding

Value range: [0, 1], Default: 1

itom.algorithms.savePtbPR(sourceObject, filename[, decimalSigns, ordinateUnit])#

saves a 1D data object to the PR format used for the reference software for roughness metrology (https://www.ptb.de/rptb) of PTB (Physikalisch Technische Bundesanstalt).

The .pr format requires the lateral scaling values in mm. If another metric unit (m, cm, mm, µm, nm) is given in the axis unit tag, an automatic conversion is applied. Else a warning is returned. The same holds for the values (ordinate). You can choose if the .pr format should contain the ordinate values in nm or µm. An auto-conversion is implemented, too.

This filter uses the hex-code DF for the german Umlaut ‘oe’ and F6 for ‘sz’ like required by the input file format description of the RPTB tool (since RPTB Version 2.01).

Parameters:

sourceObject (itom.dataObject) – 1D data object of any real data type. No invalid values are allowed.
filename (str) – Destination filename
decimalSigns (int, optional) –
Number of decimal signs (default: 6).

Value range: [0, 12], Default: 6
ordinateUnit (int, optional) –
unit of ordinate (0: nm [default], 1: µm)

Value range: [0, 1], Default: 0

itom.algorithms.saveRAS(sourceImage, filename, palette)#

Saves a real, 2D dataObject as sr-file or ras-file (Sun Raster, 8bit only).

The following conventions hold for saving the image:

fixed-point data types (uint8, uint16, uint32, int8, int16, int32) will be scaled to the supported 8bit range [0,255] and saved using the given color palette
float32 or float64 data types are scaled from [0.0, 1.0] to the supported 8bit range [0,255] and saved using the given color palette. Values outside of [0.0, 1.0] are clipped to the boundary value. Invalid values are saved as transparent values (alpha = 0).
rgba32 data type are saved depending on the given color palette. They can be saved as colored image without transparency (‘rgb’) or with considering the alpha channel as transparent values (‘rgba’). If another color palette than ‘rgb’ or ‘rgba’ is indicated, the object is at first transformed to gray and than handled as uint8 or uint16 data type.

The following base color palettes exist (further, user-defined palettes can be used, too):

gray: [0,255] gray-values, 8bit
rgba: color with transparency (converted to gray-levels however), 8bit (rgba32 input only)
rgb: color without transparency, 8bit (rgba32 input only)
grayMarked: [0,255], gray-values, 0: violet, 255: red, 8bit
falseColor, falseColorIR: [0,255], (inverse) false colors, 8bit
hotIron: [0,255], hot iron map, 8bit
red: [0,255], from black to red, 8bit
green: [0,255], from black to green, 8bit
blue: [0,255], from black to blue, 8bit

This filters uses OpenCV to save the image.

Parameters:

sourceImage (itom.dataObject) – 2D-DataObject of anytype
filename (str) – Destination filename
palette (str) – Color palette name [gray, …]

itom.algorithms.saveSDF(sourceObject, filename[, decimalSigns, verticalScale, invalidHandling, invalidValue, version])#

saves 1D and 2D dataObject to the ascii surface data file format (sdf), version aNIST-1.0 (no official standard) or aISO-1.0 (in compliance with ISO 25178-71).

Parameters:

sourceObject (itom.dataObject) – 2D-DataObject of anytype or 3-planes DataObject of uint8
filename (str) – Destination filename
decimalSigns (int, optional) –
Number of decimal signs (default: 3). For MountainsMaps reduce total number of digits to 5

Value range: [0, 12], Default: 3
verticalScale (int, optional) –
Power of 10 for the zValue (Default: -3, micrometer), only for floating point objects.

Value range: [-12, 12], Default: -3
invalidHandling (int, optional) –
Toggles NaN handling if dataObject is floating-type. 0: Write NaN (Default); 1: Skip Value, 2: Substitute by InvalidValue, 3: Substitute by BAD for MountainsMaps.

Value range: [0, 3], Default: 0
invalidValue (float, optional) –
New value for invalid substitution. Default is 0.0

All values allowed, Default: -42
version (str, optional) –
File format version: ‘aNIST-1.0’ or ‘aISO-1.0’ for DIN EN ISO 25178-71

Match: [“aNIST-1.0”, “aISO-1.0”], Default: “aNIST-1.0”

itom.algorithms.saveTXT(sourceObject, filename[, saveAsTuple, noPhysicalValues, separatorSign, separatorLines, separatorPlanes, decimalSign, wrapSign, encoding])#

saves data to an ascii-based file like txt, csv, tsv or space separated values.

Parameters:

sourceObject (itom.dataObject) – dataObject holding data to save
filename (str) – Destination file name
saveAsTuple (int, optional) –
1. save values as list of points (x, y, z).
Value range: [0, 1], Default: 0
noPhysicalValues (int, optional) –
1. ignore scale and offset
Value range: [0, 1], Default: 0
separatorSign (str, optional) – Uses this as the separator between elements. Default is space “ “.
separatorLines (str, optional) – Uses this as the separator between lines of a matrix. Default is rn.
separatorPlanes (str, optional) – Uses this as the separator between matrix planes. Default is rn.
decimalSign (str, optional) –
Uses this as the sign for decimal numbers. If <guess>, default is system default.

Match: [“<guess>”, “.”, “,”], Default: “<guess>”
wrapSign (str, optional) –
Sometimes numbers are wrapped by a sign (.e.g ‘2.3’ or “4.5”). If so, indicate the character(s) that wrap the numbers.

Match: [“<guess>”, “.”, “,”, “”], Default: <empty str>
encoding (str, optional) – encoding of text file, e.g. UTF-8, UTF-16, ISO 8859-1… Default: empty string -> the encoding is guessed due to a auto-detection of the first 64 bytes in the text file (using the BOM (Byte Order Mark)).

itom.algorithms.saveTiff(sourceImage, filename, palette)#

Saves a real, 2D dataObject as tiff-file (tagged image format, 8bit and 16bit supported).

The following conventions hold for saving the image:

fixed-point data types (uint8, uint16, uint32, int8, int16, int32) will be scaled to the supported 8bit range [0,255] or 16bit range [0, 65535] and saved using the given color palette
float32 or float64 data types are scaled from [0.0, 1.0] to the supported 8bit range [0,255] or 16bit range [0, 65535] and saved using the given color palette. Values outside of [0.0, 1.0] are clipped to the boundary value. Invalid values are saved as transparent values (alpha = 0).
rgba32 data type are saved depending on the given color palette. They can be saved as colored image without transparency (‘rgb’) or with considering the alpha channel as transparent values (‘rgba’). If another color palette than ‘rgb’ or ‘rgba’ is indicated, the object is at first transformed to gray and than handled as uint8 or uint16 data type.

The following base color palettes exist (further, user-defined palettes can be used, too):

gray: [0,255] gray-values, 8bit
gray16: [0,65535] gray-values, 16bit
rgba: color with transparency, 8bit (rgba32 input only)
rgb: color without transparency, 8bit (rgba32 input only)
grayMarked: [0,255], gray-values, 0: violet, 255: red, 8bit
falseColor, falseColorIR: [0,255], (inverse) false colors, 8bit
hotIron: [0,255], hot iron map, 8bit
red: [0,255], from black to red, 8bit
green: [0,255], from black to green, 8bit
blue: [0,255], from black to blue, 8bit

This filters uses OpenCV to save the image.

Parameters:

sourceImage (itom.dataObject) – Real, 2D data object
filename (str) – Destination filename
palette (str) – Color palette name [gray, gray16, …]

itom.algorithms.saveXPM(sourceImage, filename, palette)#

Saves a real, 2D dataObject as xpm-file (X PixMap) or xbm (X BitMap, black-white only).

The following conventions hold for saving the image:

fixed-point data types (uint8, uint16, uint32, int8, int16, int32) will be scaled to the supported 8bit range [0,255] or 16bit range [0, 65535] and saved using the given color palette
float32 or float64 data types are scaled from [0.0, 1.0] to the supported 8bit range [0,255] or 16bit range [0, 65535] and saved using the given color palette. Values outside of [0.0, 1.0] are clipped to the boundary value. Invalid values are saved as transparent values (alpha = 0).
rgba32 data type are saved depending on the given color palette. They can be saved as colored image without transparency (‘rgb’) or with considering the alpha channel as transparent values (‘rgba’). If another color palette than ‘rgb’ or ‘rgba’ is indicated, the object is at first transformed to gray and than handled as uint8 or uint16 data type.

The following base color palettes exist (further, user-defined palettes can be used, too):

gray: [0,255] gray-values, 8bit
rgba: color with transparency, 8bit (rgba32 input only)
rgb: color without transparency, 8bit (rgba32 input only)
grayMarked: [0,255], gray-values, 0: violet, 255: red, 8bit
falseColor, falseColorIR: [0,255], (inverse) false colors, 8bit
hotIron: [0,255], hot iron map, 8bit
red: [0,255], from black to red, 8bit
green: [0,255], from black to green, 8bit
blue: [0,255], from black to blue, 8bit

This filters uses Qt to save the image. In the format xbm, a threshold at 128 is applied to separate black and white.

Parameters:

sourceImage (itom.dataObject) – Real, 2D data object
filename (str) – Destination filename
palette (str) – Color palette name [gray, rgba, rgb, <any-name-of-a-color-palette>].

5.4.3. Changelog#

itom setup 1.2.0: Release