nanosurf 1.13.5
Python API for Nanosurf controllers and Nanosurf style application framework
License: MIT
Requires Python: <3.15,>=3.10

# Nanosurf Python library and application package

The Nanosurf Python package contains classes and functions for the following topics:

* Remote control of Nanosurf Studio and classic Nanosurf Atomic-Force-Microscopes
* A large number of general functions for data analysis
* Application Framework to create powerful graphical applications based on QT
* MacOS and Linux platform can use the library for off-line analysis
* Multiple demo applications

## Prerequisites

* Python 3.10 up to 3.13 installed on Windows OS/Mac or any other supported operating system. Get the installation from 'python.org'
* Nanosurf Studio or any classic Nanosurf controller software with 'Scripting Interface' option activated

## Installation and upgrading

To install the package, open a Windows Command Prompt and run:

```shell
pip install nanosurf
```

To upgrade your nanosurf package to the newest version,
open Windows Command Prompt and run:

```shell
pip install nanosurf -U
```

## Running the examples

In the library, Nanosurf provides a documentation, demo scripts, applications for some hardware addons and templates to give you a quick start.
They are in the nanosurf package sub folders "app" and "doc". But where are they on your system?

Depending on the exact installation of python, the package folders can be at very different places.
Open Windows Command Prompt and type:

```python
python 
>>> import nanosurf
>>> nanosurf.help()
```

The output of this command print the exact path to the app and doc folder.

We suggest to use Visual Studio Code as your IDE to run, write and debug your Python code.
Use one of path to open the example scripts

## AFM Software Programmers Manual

The classic Nanosurf AFM Control Software has a own programmers manual and can be found in the Scripting Manual
in Nanosurf controller software under Help tab:
Help -> Manuals -> Script Programmers Manual

Unfortunately the Nanosurf Studio application do not yet have its own programmers manual. But we are working hard to provide this.

## Library Version History

* v1.13.5:
  * Update: Win32COM automation works again with changes in PySide6.10 QThread handling
  * Update: VMF Controller software handles not connected controllers better
  * Update: nhf_to_csv_exporter show file dialog if no file is provided as command line argument
  * Bugfix: nhf_to_csv_exporter was not working with Python 3.10
  * Bugfix: Some CX Software detects arbitrary devices as Accessory Interfaces

* v1.13.4:
  * Bugfix: VMF-SampleHolder-Controller software could not read eeprom content
  * Bugfix: Device driver for SSRM and tip current addon hat wrong input scaling
  * Update: TipCurrent_Addon app set tip and sample voltage channels to correct ranges
  * Update: Studio scripts emit better error messages
  * Update: Improved type hints in gui framework

* v1.13.3:
  * Library supports now Python 3.14
  * Update: Improved startup speed by delayed import of scipy and statistic library
  * Update: Improved drivers for DriveAFM Addon
  * Bugfix: Fix some bugs in bode_plot(), EEPROM writing, gui framework

* v1.13.2:
  * Update: Improve support for Nanosurf_Linux at install and runtime
  * Update: Device ID-EEPROM write supports crc checksum

* v1.13.1:
  * Bugfix:nhf_reader - creating and instance without filename reported a "File does not exist" error

* v1.13.0:
  * New: demo_nhf_to_csv_export - Convert Studio generated data files to general text based file
  * Update: vmf_sample_holder_controller: v2.4. Auto remember last position, add "out-of-plane"-field support, ...
  * Update: nhf_reader: support for channels in measurement group level, calculation of spec_offset and spec_points
  * Python 3.9 support removed: This enables us to use new python features (e.g. 'match' statement, cleaner type hints)
  * PySide2 support removed
  * New: gui elements for horizontal and vertical lines and spacers added (NSFH/VLine, NSFH/VSpacer classes)
  * New: device driver for embedded adc module (devices.i2c.adc_module_7172)

* v1.12.3
  * Bugfix: nhf_reader: Again, dataset conversion to some units with segment.read_channel() could go wrong

* v1.12.2
  * Bugfix: installation dependency for PyQtGraph package. Currently it only works with PySide6 version <=6.9.0
  * Bugfix: nhf_reader: list of available units with dataset.units() where not always complete 
  * Bugfix: nhf_reader: Dataset conversion to some units with segment.read_channel() could sometimes not be resolved
  * Bugfix: some devices where not enabled with platform Linux
  * Update: improved versions of device drivers form TMP117/119 and SHT45
  * Update: Some improvement in I2C bus access in Nanosurf_Linux
  * New: Add support for GSSClimateSensor device

* v1.12.1
  * Bugfix: nsf_sci_edit and nsf_edit value changed registration was wrong
  * Update: studio code wrapper supports now UTF-8 strings
  * Update: Support for embedded Nanosurf_Linux without GUI
  * Update: How to install on Linux (RaspberryOS, ore others)
  * New: I2C classes for TMP119 and SHT4x chips


* v1.12.0
  * Update: nhf_reader supports v2.x files
  * New: I2C BusMaster support on Linux platform

* v1.11.0
  * Update: nhf_reader supports multiple calibrations stored in file
  * Update: nhf_reader supports data sets with NaN-Values (not-an-number) and not measured points
  * Update: nhf_reader has its own documentation in doc folder
  * New: Application for "VMF Sample Holder 2"

* v1.10.1
  * Update: Spectroscopy analysis scripts has improved fit ranges
  * Bugfix: Studio access to I2C-Bus failed
  * Bugfix: nhf_reader did not handle datasets with NaN values
  * Bugfix: nhf_reader converted small integer data ranges incorrect

* v1.10.0
  * Python 3.13 support
  * update spm_template: support of continuos measurement, input/output channels and fixation of y-range
  * Bugfix: qt_framework was not shutting down modules properly and did not store last settings

* v1.9.5
  * Bugfix: studio wrapper generator was not python 3.12 compatible
  * Limit installation of nanosurf library from 3.9 up to 3.12.

* v1.9.4
  * Bugfix: nhf_reader.read_channel() could not be call multiple times correctly
  * Bugfix: nhf_reader.read_channel() channel with "int"-unit have now np.int32

* v1.9.3
  * updated NHFFileReader class supports nhf-files version 2.1
  * Bugfix: Change list of shown items in NSFComboBox during runtime failed

* v1.9.2
  * Update installation requirements to fulfill numpy 2.0 minimal library version
  * Bugfix: Change list of shown items in NSFComboBox during runtime failed

* v1.9.1
  * Bugfix: AccessoryInterface class did not handle port-switching and slave-id readout properly
  * Bugfix: AppFramework: Module without screen could not be initialized properly

* v1.9.0
  * Python 3.12 support
  * New: Spectroscopy analysis scripts with contact mechanics models
  * New: Control app for the DriveAFM TipAccess Addon
  * New: Control app for the DriveAFM TipCurrent Addon
  * New: Platform support for Linux and Mac: installation and usage of post processing functions are possible
  * updated NHFFileReader class supports now nhf-files version 2
  * updated pyinstaller template supports now scipy import in exe
  * updated documentation with installation guide, library overview and GUI-App programming

* v1.8.6
  * Bugfix: Class AccessoryInterface did not work after update for Studio i2c support
  * Add option 'log_amp' to plot.plot_bode()

* v1.8.5
  * Bugfix: Reloading of new Studio wrapper classes in first run did not work
  * Bugfix: sci_math.compress_spectrum() keep channel name intact
  * Add option 'log_y' to plot.plot_spectrum()
  
* v1.8.4
  * Bugfix: add missing lupa files for pyinstaller
  * New: add I2C-Devices: MCP45XX, MAX1161x and MMA8451

* v1.8.3
  * Bugfix: data scaling for channels without calibration factors

* v1.8.2
  * New intro page for PyPi

* v1.8.1
  * fix python version requirement check

* v1.8.0
  * prevent installation with python 3.12 due to incompatible lupa package
  * add I2C class support for Studio
  * nanosurf.app/demo_wave_mode_nma_analysis: added Hertz model

* v1.7.2
  * New: nanosurf.app/demo_wave_mode_nma_analysis: more options for file dialog

* v1.7.1
  * Bugfix: Image Points/lines where swapped on gwy_export

* v1.7.0
  * New: nanosurf.app/demo_wave_mode_nma_analysis: script which calculates max_force, adhesion and stiffness
  * New: nanosurf.lib.util.nhf_reader: Studio measurement files (*.nhf) reader
  * New: nanosurf.lib.util.nid_reader: Classic measurement files (*.nid) reader
  * New: nanosurf.lib.util.gwy_export: Gwyddion data file creator/exporter
  * New: nanosurf.app/py_installer_template: makes creating *.exe from python apps simple
  
* v1.6.2
  * New: qt_app_framwork supports multi screen modules
  * Bugfix: settings should not be of dataclass type

* v1.6.1
  * Bugfix: pip packaging did not copy framework files

* v1.6.0
  * New: spm_template: A new template to demonstrate simple connection to CX/Studio and measure some data
  * New: app_DriveAFM_Tip_Current_Addon this app controls the amplifier of the Tip-Current Addon
  * New: demo_move_sample_stage. This demo shows basic stage movements
  * New: demo_lateral_force_signal_calibration. This demo shows how to calibrate the lateral force signal
  * New: nanosurf.plot. A package to easily plot data array from lists, numpy array, SciChannel and SciStream
  * New: nanosurf.spm.lowlevel.DataSamplerAccess. A class to make data sampling easier for CX/Studio
  * New: nanosurf.frameworks.qt_app: A framework to easily create nice Qt applications
  * Update: all applications are using the new qt_app framework of the library
  * Update: app_frequency_sweep: add logarithmic plotting capability
  * Bugfix: app_frequency_sweep: excitation mode was inverted

* v1.5.1
  * Bugfix: Do not convert Lua arrays with string-keys
  * Bugfix: Improved Python enum conversion to Lua

* v1.5.0
  * Library supports now python v3.11
  * Library supports now PySide2 and PySide6

* v1.4.1
  * bugfix: Studio vector attributes are defined as .vector instead of .value
  * improve installation instruction for editable mode

* v1.4.0
  * Add enum support for Nanosurf Studio scripting interface
  * Nanosurf Studio properties and LogicalUnits attributes have common interface style
  * Add revers ramp feature to App_Switching_Spectroscopy
  * Some small improvements to other applications

* v1.3.4
  * fix bug in frequency_sweep

* v1.3.3
  * Improve visual appearance of some nsf.gui elements
  * fix eeprom memory write access for i2c.chip_24LC34A
  * better return value for fileutil.create_unique_folder() in case of error

* v1.3.2
  * Bugfix: Studio - handling of boolean properties was not working
  * Add support for DriveAFM Camera i2c-chip

* v1.3.1
  * Bugfix: App_switching_spectroscopy - selection of output and amplitude setting had some issues

* v1.3.0
  * Add simplifies library usage is possible. Just write 'import nanosurf as nsf' and full access to sub-libraries is provided in visual studio code
  * new app: app_switching_spectroscopy provides the possibility to measure in "Switching Spectroscopy"-Mode
  * new qui elements: nsf.gui.NSFEdit and nsf.gui.NSFComboBox
  * Bugfix: Wrong number type in Python for double based property   
  * Bugfix: nsf.spm.workflow.frequency_sweep: PositionX/Y/Z was not working as output

* v1.2.0
  * Add Studio scripting support

* v1.1.0
  * Add direct I2C motor control

* v1.0.0
  * Initial release

### License

[MIT License](https://en.wikipedia.org/wiki/MIT_License)