Metadata-Version: 2.4
Name: ndtkit_api
Version: 0.0.28
Summary: This Python API provides a high-level interface to interact with the NDTkit desktop application. It allows developers to script and automate NDTkit features remotely, leveraging the full power of the underlying Java application through a simple and pythonic library.
Author-email: Cédric BERTRAND <cedric.bertrand@testia.com>
License: Copyright (c) 2025 TESTIA SAS. All Rights Reserved.
        
        ==============================================================================
        PROPRIETARY SOFTWARE LICENSE
        for the ndtkit_api
        ==============================================================================
        
        This Application Programming Interface, including its documentation, data structures, and all related materials (collectively, the "API"), is proprietary software and the confidential intellectual property of TESTIA SAS ("Licensor").
        
        **1. LICENSE REQUIREMENT**
        
        Access to, and use of, this API is strictly conditional upon and requires that you (or the legal entity you represent) hold a valid, active, and fully paid commercial software license for the "NDTkit" software (the "NDTkit License").
        
        Any access or use of this API without a valid NDTkit License is unauthorized, constitutes a material breach of this agreement, and is a violation of Licensor's intellectual property rights.
        
        **2. GOVERNING AGREEMENT**
        
        Your use of this API is governed by the terms and conditions of your NDTkit License agreement, or a separate API Terms of Service provided by Licensor, whichever is applicable (the "Governing Agreement"). By accessing or using this API, you represent and warrant that you hold a valid NDTkit License and you agree to be bound by the terms of the Governing Agreement.
        
        **3. TERMINATION OF RIGHTS**
        
        Your right to use this API will terminate immediately and automatically, without notice, if your NDTkit License expires, is terminated, or is otherwise no longer valid. Upon such termination, you must cease all use of the API and destroy any related materials in your possession.
        
        **4. RESTRICTIONS**
        
        You may not, without express written permission from Licensor:
        a) Sublicense, sell, rent, lease, or otherwise distribute the API to any third party.
        b) Reverse engineer, decompile, disassemble, or attempt to derive the source code of the API.
        c) Use the API to create a product or service that competes with the NDTkit software or the API itself.
        d) Use the API for any purpose not expressly permitted by your Governing Agreement.
        
        **5. NO OTHER RIGHTS GRANTED**
        
        This license file does not grant you any rights to use, copy, modify, or distribute the API. All rights not expressly granted herein are reserved by TESTIA SAS.
        
        **6. DISCLAIMER OF WARRANTY**
        
        THE API IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
        
        **7. LIMITATION OF LIABILITY**
        
        IN NO EVENT SHALL TESTIA SAS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE API OR THE USE OR OTHER DEALINGS IN THE API.
        
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: py4j
Requires-Dist: pyinstaller
Dynamic: license-file

# NDTkit Python API

![Python API for NDTkit](https://img.shields.io/badge/API-Python-blue.svg)
![License](https://img.shields.io/badge/License-Proprietary-green.svg)

This Python API provides a high-level interface to interact with the [NDTkit](https://www.testia.com/product/ndtkit-ut/) desktop application. It allows developers to script and automate NDTkit features remotely, leveraging the full power of the underlying Java application through a simple and pythonic library.

## 📋 Prerequisites

Before using this API, you must have:

1.  **Python 3.11+** installed.
2.  The **NDTkit 4.1+** installed.
3.  [OPTIONAL] For developers that want to add user interface directly in NDTkit (side panel or new menu), [Open JDK 21](https://docs.aws.amazon.com/corretto/latest/corretto-21-ug/downloads-list.html) must be installed.

## ⬇️ Installation & Configuration

1.  **Install the library**

```
pip install ndtkit-api
```

2.  **Configure the connection**: This library needs to connect to NDTkit's socket server. No change is needed unless you explicitly changed the NDTkit's socket server configuration. If the NDTkit software needs to be launched from this library, set `NDTKIT_FILEPATH`, this will automatically launch NDTkit if no socket server is detected. Here is an example on how to configure these variables:

    ```python
    from ndtkit_api.config import config

    config.SERVER_HOST = "127.0.0.1"          # default value
    config.SERVER_PORT = 32146                # default value
    config.SERVER_CONNECTION_TIMEOUT = 120    # default value
    config.NDTKIT_FILEPATH = "C:/Users/admin/NDTkit/NDTkit.vbs"
    ```

    - **`SERVER_HOST`**: The IP address of the machine running NDTkit. Use `127.0.0.1` if it's on the same machine.
    - **`SERVER_PORT`**: The port for the socket communication. This must match the port of the NDTkit socket server.
    - **`SERVER_CONNECTION_TIMEOUT`**: After this timeout (in seconds), the API will stop attempting to connect to NDTkit's socket server.
    - **`NDTKIT_FILEPATH`**: Your Python source code will try to launch NDTkit, using this path, if no socket server is detected.

## 📝 Usage Example

Here is a simple example showing how to open a C-Scan, modify a pixel, and save it to a new file.

```python
# examples.py

from ndtkit_api import NDTKitCScanInterface, ndtkit_socket_connection
from ndtkit_api.model.frame.NICartographyFrameCScan import NICartographyFrameCScan


def change_pixel_value(input_file: str, output_file: str):
    """
    Opens a C-Scan, modifies the value of the first pixel, saves it,
    and re-opens it for display.
    """
    print(f"Opening C-Scan: {input_file}")
    # The server is launched automatically if not running
    cscan: NICartographyFrameCScan = NDTKitCScanInterface.open_cscan(input_file)

    if not cscan:
        print("Failed to open C-Scan.")
        return

    print(f"C-Scan opened successfully with UUID: {cscan.get_uuid()}")

    print("Retrieving data matrix...")
    data: list[list[float]] = cscan.get_data()
    print(f"Original value at [0][0]: {data[0][0]}")

    # Modify the data
    data[0][0] = 12.0
    print(f"Setting new value at [0][0] to 12.0")
    cscan.set_data(data)

    print(f"Saving modified C-Scan to: {output_file}")
    NDTKitCScanInterface.save_cscan(cscan, output_file)

    print("Re-opening the saved C-Scan to verify.")
    NDTKitCScanInterface.open_cscan(output_file, displayResult=True)
    print("Done.")


if __name__ == "__main__":
    ndtkit_socket_connection.launch_ndtkit() # Launch NDTkit if it is not already done
    # Make sure to use paths that are valid on your system
    input_cscan_path = "C:/Users/admin/Documents/Data/dd_carto.nkc"
    output_cscan_path = "C:/Users/admin/Documents/Data/result.nkc"
    change_pixel_value(input_cscan_path, output_cscan_path)

```

You can find **practical usage examples** for this API on the [dedicated Github page](https://github.com/cedric-bertrand-testia/ndtkit-python-api-examples).

## ✨ A class/method is available in the Java API but it is not appearing in this Python API

It can be reachable anyway, it's just the auto-completion of your IDE that is not working. Actually this Python API is using [py4j](https://www.py4j.org/) that allows to access any Java API function.
Here's an example on how to access to `agi.ndtkit.api.NDTKitCScanInterface.openCScan(String)` without using directly the API:

```python
from ndtkit_api.ndtkit_socket_connection import gateway

gateway.jvm.agi.ndtkit.api.NDTKitCScanInterface.openCScan("path/to/my/cscan") # type: ignore
```

So please refer to the NDTkit Javadoc to have an exhaustive look at all the available actions and call them using this solution if they are not available directly in this Python API.

## 🛠️ CLI workflow (create / modify / deploy)

This library comes with several command lines that help you to create a new plugin. Here are the different commands that can be called:

- `ndtkit create`: start a prompt that guide you for creating a new plugin

- `ndtkit modify`: allows to change some configurations of the plugin (eg: `ndtkit modify --port 1212`)

- `ndtkit deploy`: deploys your plugin so it is loaded by NDTkit. Don't forget to restart NDTkit to take the changes into account.

> **Note:** If a .spec file matching the plugin name or the target script is detected, the script will prioritize it. This allows you to define complex build rules (like custom data inclusions, specific binary bundles, or advanced hooks) directly in the .spec file.

> **Note:** On subsequent runs, the script will reuse the settings from `build_config.json`. If you need to change your configuration (e.g., to target a new version), you can simply delete this file and run `ndtkit_deploy` again to be re-prompted.
