Opening SPM Files
=================

SPIEPy does not contain any functions to open SPM files. In this way SPIEPy can
be used by all scanning probe microscopy systems. To open a SPM file you must
write your own Python code or use code that is provided by others. There is a
Python library available for accessing the result files of the Scienta Omicron
MATRIX Control System, the author is the very same as the
author of this library. The library is called
`access2theMatrix <https://pypi.org/project/access2theMatrix/>`_. It can
easily be installed with :command:`pip`::

	> pip install access2theMatrix

Opening Scienta Omicron MATRIX Control System Result Files
-------------------------------------------------------------------

In the example, below, the MATRIX Control System has stored the acquired data in
the folder :file:`c:\\data`. In addition to the result data files the folder
must also contain the result file chain, see the MATRIX Application Manual for
SPM. The file :file:`20140325-092702_AFM_NonContact_QPlus--51_1.Z_mtrx` will be
opened and the ``backward/up`` trace will be selected.

::

	>>> import access2thematrix
	>>> mtrx_data = access2thematrix.MtrxData()
	>>> data_file = r'c:\data\20140325-092702_AFM_NonContact_QPlus--51_1.Z_mtrx'
	>>> traces, message = mtrx_data.open(data_file)
	>>> print(message)
	Successfully opened and processed data file 20140325-092702_AFM_NonContact_QPlus--51_1.Z_mtrx.
	>>> traces
	{0: 'forward/up', 1: 'backward/up', 2: 'forward/down', 3: 'backward/down'}
	>>> im, message = mtrx_data.select_image(traces[1])
	>>> print(message)
	Trace backward/up selected.
	>>> im.data
	array([[ -1.80605572e-08,  -1.80625201e-08,  -1.80663057e-08, ...,
	         -1.82079808e-08,  -1.82142887e-08,  -1.82174186e-08],
	       [ -1.80587456e-08,  -1.80613477e-08,  -1.80623131e-08, ...,
	         -1.82091517e-08,  -1.82156607e-08,  -1.82195526e-08],
	       [ -1.80513618e-08,  -1.80510353e-08,  -1.80531660e-08, ...,
	         -1.82131799e-08,  -1.82177880e-08,  -1.82229330e-08],
	       ..., 
	       [ -1.79789472e-08,  -1.79819920e-08,  -1.79856806e-08, ...,
	         -1.81261956e-08,  -1.81293811e-08,  -1.81332706e-08],
	       [ -1.79804649e-08,  -1.79810591e-08,  -1.79850527e-08, ...,
	         -1.81223942e-08,  -1.81250894e-08,  -1.81293146e-08],
	       [ -1.79775549e-08,  -1.79791702e-08,  -1.79830948e-08, ...,
	         -1.81149155e-08,  -1.81181441e-08,  -1.81199908e-08]])
	>>> im.data.shape
	(240, 320)
	>>> im.angle
	122
	>>> im.height
	3.0000000000000004e-09
	>>> im.width
	4e-09
	>>> im.x_offset
	-8.7804110391206612e-08
	>>> im.y_offset
	1.86005503318584e-07
	>>> 

The image data and the metadata angle, height, width, x_offset and y_offset are
stored in the object *im* which is an access2theMatrix Image Structure object.

.. Note::
	To use the object *im* with the SPIEPy library, *im* must change from
	access2theMatrix Image Structure object to SPIEPy Image Structure object.

Changing the class of *im*::

	>>> import spiepy
	>>> im.__class__ = spiepy.Im