Metadata-Version: 2.4
Name: nmixstudio
Version: 1.2.0
Summary: Python API for controlling and monitoring NMIXStudio (NanoMagnetics Instruments)
Author: NanoMagnetics Instruments
Author-email: nmi.swteam@nano.com.tr
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31
Requires-Dist: numpy>=1.24
Requires-Dist: matplotlib>=3.7
Requires-Dist: pillow>=9.0
Requires-Dist: tqdm>=4.60
Requires-Dist: PyVISA>=1.12
Provides-Extra: andor
Requires-Dist: pylablib; extra == "andor"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

**NMIXStudio Library Description**

The **NMIXStudio Python Library** is a powerful API designed for seamless interaction with **NMIXStudio systems**, providing comprehensive tools for system customization, real-time monitoring, and data management. Its modular structure allows easy integration into scientific and industrial workflows.

Key features include:

- **Device Control**:
  - Complete control over scanning processes, voltage configurations, and offset adjustments.
  - Optimizes system performance with automatic calibration and setup features.
- **Real-Time System Monitoring**:
  - Provides real-time access to essential metrics like system status and scan progress.
  - Delivers detailed feedback on scanning status, voltage levels, and system activities.
- **Data Management**:
  - Records, organizes, and analyzes scanned images and system readings.
  - Offers the ability to manage image containers effectively.
- **Customizable Solutions**:
  - Configures scanning parameters and other settings to meet experimental or industrial requirements.
  - Its modular design enhances system scalability.

This library is an ideal tool for automating workflows, optimizing device performance, and developing custom applications.

# Prerequisites

- **Operating System:** Windows 10 or later.
- **Python Version:** Python versions 3.9 to 3.12. Download Python from python.org.
- **NMIX Software:** The NMIXStudio software must be installed, and its API feature should be activated.
- **Network Access:** The ezAFM+ device must be accessible via its designated IP address and port.
- **pip Package Manager:** The Python pip package manager is required to install the library.
- **Dependencies:** All required dependencies are installed automatically during the library setup.
- **Development Environment (Recommended):** Using Visual Studio Code is recommended for writing, debugging, and running Python scripts.

**Note:** Ensure your Python environment is properly configured before proceeding with the installation.

# Installation and Upgrading

- **To Install the NMIXStudio Python Library:**
  - Open a Windows Command Prompt or terminal with Python installed.
  - Enter the following command:

pip install nmixstudio

- **To Upgrade to the Latest Version of the NMIXStudio Library:**
  - Use the following command:

pip install nmixstudio -U

**Note:** Ensure your Python environment meets all the prerequisites listed before proceeding with the installation or upgrade.

# Running the Examples

The **NMIXStudio Python Library** provides comprehensive documentation, sample scripts, and application templates to help users get started quickly. These resources are organized into separate directories such as Docs and Samples within the package.

To locate these files on your system, follow these steps:

1. Open a terminal or command prompt with Python installed.
2. Enter the following commands to access the library's help feature:

python

\>>> import NMIXStudio

\>>> NMIXStudio.help()

1. The output will display the exact paths to the documentation (Docs) and example scripts (Samples). For instance:
    1. **Docs**: Contains the PDF manual and library overview files.
    2. **Samples**: Includes subfolders like Basics and Experiments with practical examples.

We recommend using **Visual Studio Code** or a similar IDE for writing, debugging, and running Python scripts. You can explore the examples in the Samples folder to better understand how to interact with the NMIXStudio API and customize it for your needs.

# Connection and Logging

- Every request uses a timeout of 5 s (connect) / 60 s (read). It can be changed per endpoint, e.g. `NMIEndpoint("192.168.10.110", 9025, timeout=(5, 120))`.
- Failed requests and server error messages are printed to the console and written to the `NMIXStudio` logger, and the method returns `None`.
- The reason of the last failure is kept in `Endpoint.last_error` (`{"command", "status_code", "message"}`; `None` after a successful request).
- Console printing can be turned off with `NMIXStudio.set_verbose(False)`; the messages are still logged.
- The library does not write a log file by default. To write the library logs to a file:

\>>> import NMIXStudio

\>>> NMIXStudio.enable_file_logging("logFile_API.log")

# Reading Values

Some flags come from the server as JSON booleans and others as the strings `"True"`/`"False"` (for example `SCAN().Get_IsScanning()`, `STATUS().Get_DashboardStatus()`, `PID().Get_PID()`). In Python `bool("False")` is `True`, so use the helpers:

\>>> from NMIXStudio import to_bool, to_float

\>>> to_bool(Device.SCAN().Get_IsScanning()["IsScanning"])

- `to_bool(value)`: `"True"/"False"`, `"1"/"0"` and booleans.
- `to_float(value)`: numbers, decimal-comma strings (`"1,25"`) and `"NaN"`/`"Infinity"`.
- `get_first(response, "NewKey", "OldKey")`: first key that exists in a response.

# Modules

| Accessor | Module | Notes |
|---|---|---|
| `STATUS()` | APP | System state, dashboard, `DeviceInformations()` |
| `SYSTEMREADINGS()` | SystemReadings | Live signals; `Get_SystemReadingsWithTimestamp()` adds the frame time |
| `SCAN()` | Scan | Scan geometry, speed, start/stop, save folder/name, scan channel selection |
| `SCANNEDIMAGES()` | ScannedImages | Image containers, image data (any frame), `Save_Container()` |
| `IMAGETOOLS()` | ImageTools | GUI Image Tools: analysis (cross section, roughness, histogram, distance, angle, pixel), processing that adds a new image (plane/line correction, scars, flip/rotate/crop, filters), export on the instrument PC |
| `OPTIONS()` | Options | SPM type, AFM mode, XY/Z scale |
| `XYOFFSET()` | XYOffset | XY offset (ramped or direct), GUI offset updater |
| `PID()` | PID | P/I/D, set point, enable, polarity |
| `APPROACH()` | Approach | STM motor card / XY Motor window moves, `Get_MotorState()`; Z moves in AFM modes go through `ZMOTOR()` |
| `ZMOTOR()` | ZMotor | ezAFM Z motor (AFM modes): `Get_State()`, approach / retract step, auto land, park, remove, timed jog (max 5 s), stop |
| `AUTOTUNE()` | AutoTune | Frequency sweep, excitation, Null Phase, Q factor |
| `IVCURVE()` | IVCurve | IV spectroscopy (bias sweep) |
| `PHOTODIODE()` | PhotoDiode | Photodiode signals, laser power/RF, laser on/off |
| `VBIAS()` | VBias | Bias DC/AC, /500 divider, polarity; `Get_Min/MaxDCOffset()` give the allowed range (AC amplitude and AFM mode) and `Set_DCOffset()` refuses values outside it |
| `WINDOWCONTROLLER()` | WindowControl | GUI tool windows |

Laser: `PHOTODIODE().Set_LaserOn()` / `Set_LaserOff()` switch the laser. `Set_LaserEnable()` / `Set_LaserDisable()` only unlock or lock the GUI "Laser" checkbox.

Units: XY lengths (offsets, image size, `CustomScanner` sizes) are in the GUI XY scale unit (`OPTIONS().Get_XYScale()`). IV curve bias values are in mV.

# Changelog

## 1.2.0

Needs NMIXStudio software with the ZMotor API (November 2026); older software answers "Route not found" and the `ZMOTOR()` methods return `None`.

- New `ZMOTOR()` controller for the ezAFM Z motor: `Get_State()` (positions in mm, limits, busy flags, land position), `Get/Set_JogSpeed`, `Set_ApproachStep`, `Set_RetractStep`, `Set_Jog(direction, duration_ms, speed=None)` (the server stops the motor after at most 5000 ms), `Set_AutoLand`, `Set_GotoPark`, `Set_Remove`, `Set_Stop`. New sample `ZMotor.py`.
- Server changes picked up by the library without code changes: `APPROACH().Set_Move*` now fail instead of reporting success when nothing moves (Z moves in AFM modes go through `ZMOTOR()`), `Set_Stop` also stops the Z motor, `Get_IsInit` sees the Approach view; `STATUS().Get_DashboardStatus()` has `StatusLed` and `ZOffsetUnit`, `DeviceType` is `"NMIXStudio"`; `VBIAS().Get_Min/MaxDCOffset()` return the allowed range and `Set_DCOffset()` refuses values outside it.
- Removed `HALLCARD()` (NMIXStudio has no HallCard module; every call returned `None`).
- `SystemReadingsChannels` lists only the fields NMIXStudio sends.

## 1.1.0

Needs NMIXStudio software with the November 2026 API update; older software answers "Command not found" / "Route not found" and the method returns `None` with `Endpoint.last_error` set.

- New `IMAGETOOLS()` controller, one method per command:
  - Analysis (read only): cross section, distance, angle, pixel value, roughness, histogram, image info.
  - Processing, each adds a new image to the container and selects it in the GUI (GUI undo stack): plane/line corrections, scar removal, flip/rotate/crop, filters.
  - Export on the instrument PC: `Export_Image`, `Export_MultiFrame` (poll `Get_ExportStatus`).
- New `IVCURVE()` controller (all IV curve commands; `Get_ChartData(channel)` returns `(keys, values)`). Channels: TunnelCurrent, LIA1RMS, LIA1Phase, DeltaF, LIA2RMS, LIA2Phase, Spare1, Spare2, OpticalZSensor, NormalizeConductance, FN, FL, FT, WorkFunction.
- New commands: Approach `Get_MotorState`; Scan `Get/Set_ImageDirectory`, `Get/Set_ImageName`, `Get_ScanSpeedTypeList`, `Get/Set_ScanSpeedType`, `Get_ScanChannels`, `Set_ScanChannelSelected`, `Set_ScanChannels`; ScannedImages frame index, `Get_FrameCount`, `Save_Container`; AutoTune `Get/Set_ExcitationSetMode`, `Get_MaxExcitation`, `Get_ExcitationRead`, `Get_QFactor`, `Get_FreeRms`, `Get/Set_AutoRetract`, `NullPhase`; VBias `Get_MaxACAmplitude`, `Get_IsSwForcedDC`, `Get/Set_DividerEnabled`, `Get/Set_Polarity`; PhotoDiode `Set_LaserOn`, `Set_LaserOff`, `Get_IsLaserChangeEnabled`; SystemReadings `Get_SystemReadingsWithTimestamp`; XYOffset `Get_IsGuiOffsetUpdaterRunning`.
- PID P/I/D values may have a fraction (0..100 %).
- `STATUS().DeviceInformations()`; enum values are checked before sending.
- Request layer: `Endpoint.last_error`, `set_verbose()`, HTTP status and plain-text errors are reported.
- `CustomScanner`: ramps to the first pixel before stopping the GUI offset updater, restores the updater and the original offset in all cases.
- Samples fixed (`to_bool` for `IsScanning`, units, laser lock vs. on/off); new `IVCurve.py`, `ImageTools.py`, `ScanCustom.py`.
- Packaging: `package_data` paths fixed, `andor` extra.
