.. _frame_analysis_workflow:

Picture Frame DIC Analysis Workflow
===================================

This document outlines the workflow for processing grid data in the Direct Image Correlation (DIC) analysis of a picture frame test. 
The core logic is encapsulated in the ``process_grid_data`` method of the ``DICGrid`` class.

Overview
--------

The processing pipeline converts raw coordinate data from tracking markers into full-field strain maps through the following four stages:

1.  **Data Ingestion**: Raw image paths and point coordinates are stored.
2.  **Displacement Calculation**: Computes the vector difference between current and reference configurations.
3.  **Field Interpolation**: Converts sparse marker data into a dense grid.
4.  **Strain Computation**: Derives strain tensors from the displacement field.

Detailed Workflow
-----------------

Step 1: Displacement Calculation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The method first determines the displacement field (:math:`\mathbf{u}`) based on the input coordinates.

* **Input**: ``current_points`` and ``reference_points``.
* **Logic**:
    * If ``remove_rigid_transform`` is ``True``: The method calculates displacement after subtracting rigid body motions (translation/rotation) via ``compute_disp_and_remove_rigid_transform``.
    * Otherwise: It calculates raw displacement via ``compute_displacement``.
* **Output**: ``self.disp``

Step 2: Grid Interpolation
~~~~~~~~~~~~~~~~~~~~~~~~~~

To move from discrete marker points to a continuous field, the data is passed to the **GridInterpolator**.

* **Class**: ``GridInterpolator``
* **Method**: ``interpolate_displacement``
* **Action**: Maps the irregular ``self.disp`` data onto the regular mesh defined by ``self.grid_x`` and ``self.grid_y``.
* **Output**: ``self.disp_x``, ``self.disp_y`` (Dense displacement fields).

Step 3: Strain Calculation
~~~~~~~~~~~~~~~~~~~~~~~~~~

Finally, the dense displacement fields are differentiated to obtain strain.

* **Class**: ``StrainCalculator``
* **Method**: ``compute_strain``
* **Parameters**:
    * ``method``: Accepts ``cauchy``, ``2nd_order`` (Green-Lagrange), or ``log`` (Hencky).
* **Output**:
    * Normal Strains: ``self.strain_xx``, ``self.strain_yy``
    * Shear Strain: ``self.strain_xy``

API Reference
-------------

.. py:method:: process_grid_data(self, reference_image, image, reference_points, current_points, interpolation_method, strain_type, remove_rigid_transform=False)

   Orchestrates the DIC processing pipeline.

   :param reference_image: Filename or path of the reference (undeformed) image.
   :type reference_image: pathlib.Path | str
   :param image: Filename or path of the current (deformed) image.
   :type image: pathlib.Path | str
   :param reference_points: Coordinates of markers in the reference configuration.
   :type reference_points: np.ndarray
   :param current_points: Coordinates of markers in the current configuration.
   :type current_points: np.ndarray
   :param interpolation_method: The algorithm used to grid the scattered data (e.g., 'linear', 'cubic').
   :type interpolation_method: str
   :param strain_type: Definition of strain to compute ('green_lagrange', 'cauchy-eng', '2nd_order', 'log').
   :type strain_type: str
   :param remove_rigid_transform: If True, rigid body rotation and translation are removed before strain calculation.
   :type remove_rigid_transform: bool, optional
   :return: The computed displacement vector.