.. _ut_converters:

Universal Testing (UT) Machine Converters
=========================================

.. sectnum::

The ``py3dic`` package provides tools to convert proprietary data formats from various Universal Testing machines into the standardized agnostic format required for DIC analysis.

Supported Manufacturers
-----------------------

Currently, converters for the following manufacturers are tracked:

* **Jinan (Max Testing Software)**: Fully supported and integrated.
* **Imada**: Currently in development (not yet available in the package).

Jinan (Max Testing) Converter
-----------------------------

The Jinan converter is exposed as a command-line tool.

**Usage:**

Once the package is installed, you can invoke the converter directly from your terminal:

.. code-block:: console

   py3dic-jinan-converter 

The command brings a tk interface to select the input file. The output files (``.autd`` and ``.json``)
are saved in a new folder named ``data_tensile`` in the same directory as the input file. This is the standard input. 

.. note::

    Users should put the data tensile file in the experiment root directory (e.g., ``test_20251228_1234``) next to the image direcotry
    and then run the converter and select the file. The result will create a directory structure that can be automatically detected by the DIC analysis pipeline.

**Internal Reference:**

For developers, this command is mapped via the following entry point in the package configuration:

.. code-block:: python

   entry_points={
       'console_scripts': [
           'py3dic-jinan-converter = py3dic.testing_machine.max_testing.__main__:main',
       ],
   }


Imada Converter
---------------

This has been tested with `MX2 series | IMADA specializes in force measurement <https://www.forcegauge.net/en/product/detail/mx2010>`_.

This is still in development and not yet available in the package.

The main issue with the IMADA software is that the data are stored in 2000Hz and so reduction is required. 

The following example shows how to use the converter:

.. code-block:: python 

    #%%
    import pathlib
    import numpy as np
    import pandas as pd

    from py3dic.testing_machine.imada import ImadaUTFileProcessor   
    # import py3dic.g_machine.imada as imada_ut_file_processor

    #%%
    FILENAME = "./example_imada.csv"

    #%%
    jfp = ImadaUTFileProcessor(FILENAME)
    jfp.decimation = 400
    metadata, data_df = jfp.load_data()
    #%%
    jfp.save_data()

    # %%
    jfp.data_df.plot(x='disp_mm', y='force_N', kind='scatter', title='Imada UT Data')
    # %%
    py3dic-imada-converter


.. note::
    
    Make note of the `decimation` factor used in the converter. This is used to 
    reduce the data to a more manageable size. 

    In this example the **decimation** factor is set to 400, which means that every 400th data point is used. 
    This results in a sampling rate of 5Hz.