Metadata-Version: 2.4
Name: pla_analysis
Version: 0.1.2
Summary: Una librería simple para hacer un análisis visual de pruebas de tracción y seguimiento de cuerpos 3D.
Author-email: Haritz Aseguinolaza <haritz.aseguinolaza@alumni.mondragon.edu>, Aimar Seco <aimar.seco@alumni.mondragon.edu>, Aratz Zabala <aratz.zabala@alumni.mondragon.edu>, Aitor Otzerin <aitor.otzerin@alumni.mondragon.edu>
License: MIT License
        
        Copyright (c) 2026 Haritz Aseguinolaza, Aimar Seco, Aratz Zabala, Aitor Otzerin
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE 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. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS 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 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Keywords: vision artificial,ingenieria,tensile test,opencv,tracking,pla,analysis,3d,body,displacement
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opencv-python
Requires-Dist: numpy
Requires-Dist: matplotlib
Dynamic: license-file

# PLA Analysis Library

![Version](https://img.shields.io/pypi/v/pla_analysis)
![Python](https://img.shields.io/badge/python-3.7%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)

**pla_analysis** es una librería de visión artificial diseñada para la automatización y análisis de ensayos mecánicos. Esta herramienta permite extraer datos cuantitativos precisos (desplazamiento, elongación) a partir de grabaciones de vídeo o secuencias de imágenes, eliminando la necesidad de sensores de contacto físicos.

## Instalación

Puedes instalar la librería directamente desde PyPI:

```bash
pip install pla_analysis
```

## Guía de Uso

La librería se divide en dos módulos especializados según el tipo de ensayo mecánico. A continuación se detalla el funcionamiento de cada uno.

---

### 1. Módulo Tensile (Extensometría Óptica)

Este módulo automatiza la medición de la elongación en ensayos de tracción mediante el seguimiento de dos marcas físicas en la probeta.

#### Requisitos de Entrada
* **Input:** Una carpeta (directorio) que contenga la secuencia de imágenes (frames) del ensayo ordenados cronológicamente.
* **Probeta:** Debe tener **dos líneas negras horizontales** marcadas sobre un fondo claro.

#### Código de Ejemplo

```python
import pla_analysis

# Ruta a la carpeta que contiene las imágenes .jpg/.tif/.png
carpeta_frames = "C:/ruta/a/mis_frames_traccion"

# Ejecutar análisis
# l0_mm: Distancia inicial real entre las dos líneas (Default: 35.0 mm)
# a0_mm2: Área transversal de la probeta (Default: 15.0 mm^2)
pla_analysis.tensile.analyze(carpeta_frames, l0_mm=35.0, a0_mm2=15.0)
```

#### Flujo de Trabajo Interactivo

1.  **Selección de ROI (Región de Interés):**
    Al ejecutar el código, se abrirá el primer frame. Debes dibujar un recuadro con el ratón que cumpla dos condiciones vitales:
    * **Debe contener AMBAS líneas negras.**
    * Debe tener cierta **holgura vertical** (hacia donde se estira la probeta) para no perder las líneas durante el ensayo.
    * **Eficiencia:** Intenta ajustar el ancho horizontalmente a la probeta. Seleccionar una región innecesariamente grande aumentará el coste computacional y podría ralentizar el análisis.

2.  **Análisis en Vivo:**
    El programa procesará la secuencia mostrando un dashboard con la detección de líneas y la gráfica de elongación generándose frame a frame.

3.  **Resultados:**
    Al finalizar, se mostrará el desplazamiento máximo en la terminal y se abrirá una ventana con la gráfica final detallada de `Elongación (mm) vs Tiempo`.

---

### 2. Módulo Body3D (Seguimiento de Flexión)

Diseñado para rastrear el desplazamiento de un punto específico (centroide) en ensayos de flexión o movimiento de cuerpos rígidos.

#### Preparación del Experimento (Importante)
Para garantizar el correcto funcionamiento de la visión artificial, el vídeo de entrada debe cumplir:
* **Contraste:** La probeta debe ser clara (blanca) y el fondo también blanco o muy claro.
* **Marcador:** Dibuja un **punto único negro o azul oscuro** en la zona que deseas analizar.
* **Edición:** Se recomienda recortar el vídeo previamente para eliminar tiempos muertos al inicio o final. Cuanto menos "relleno" tenga el vídeo, más rápido y preciso será el análisis.

#### Código de Ejemplo

```python
import pla_analysis

# Ruta al archivo de video (.mp4, .avi, etc.)
video_path = "C:/ruta/a/ensayo_flexion.mp4"

# save_video=True generará un archivo .mp4 con el resultado visual superpuesto
pla_analysis.body3d.analyze(video_path, save_video=True)
```

#### Flujo de Trabajo Interactivo

1.  **Calibración de Escala:**
    El sistema necesita transformar píxeles a milímetros.
    * Haz clic en **dos puntos** de la imagen cuya distancia real conozcas (por ejemplo, el ancho de la probeta).
    * Introduce en la terminal la distancia real en milímetros (ej. `10.5`).

2.  **Selección de ROI:**
    Selecciona un recuadro que englobe la zona por donde se moverá el punto negro. Asegúrate de dar suficiente **holgura** para que el punto no se salga del cuadro durante la flexión máxima.

3.  **Ajuste de Umbral (Thresholding):**
    Aparecerá una ventana con una barra deslizante.
    * Mueve la barra hasta que **solo el punto negro** sea visible en negro y el resto de la imagen aparezca totalmente blanca.
    * Pulsa `ENTER` para confirmar.

4.  **Resultados y Exportación:**
    El sistema generará automáticamente en tu carpeta de ejecución:
    * `resultado_analisis.mp4`: Vídeo del dashboard en tiempo real.
    * `reporte_comparativo.png`: Imagen estática comparando el estado inicial (reposo) con el de máximo desplazamiento.

---

## Autores

Proyecto desarrollado por alumnos de Mondragon Unibertsitatea:

* **Haritz Aseguinolaza**
* **Aimar Seco**
* **Aratz Zabala**
* **Aitor Otzerin**

## Licencia

Este proyecto se distribuye bajo la licencia MIT. Consulta el archivo `LICENSE` para más información.
