Metadata-Version: 2.4
Name: pyxel-dic
Version: 2026.10.8
Summary: Finite Element (FE) Digital Image/Volume Correlation (DIC/DVC) library for experimental mechanics
Home-page: https://github.com/jcpassieux/pyxel
Author: Jean-Charles Passieux
Author-email: JC Passieux <passieux@crans.org>
License: 
          CeCILL FREE SOFTWARE LICENSE AGREEMENT
        
        Version 2.1 dated 2013-06-21
        
        
            Notice
        
        This Agreement is a Free Software license agreement that is the result
        of discussions between its authors in order to ensure compliance with
        the two main principles guiding its drafting:
        
          * firstly, compliance with the principles governing the distribution
            of Free Software: access to source code, broad rights granted to users,
          * secondly, the election of a governing law, French law, with which it
            is conformant, both as regards the law of torts and intellectual
            property law, and the protection that it offers to both authors and
            holders of the economic rights over software.
        
        The authors of the CeCILL (for Ce[a] C[nrs] I[nria] L[ogiciel] L[ibre]) 
        license are: 
        
        Commissariat à l'énergie atomique et aux énergies alternatives - CEA, a
        public scientific, technical and industrial research establishment,
        having its principal place of business at 25 rue Leblanc, immeuble Le
        Ponant D, 75015 Paris, France.
        
        Centre National de la Recherche Scientifique - CNRS, a public scientific
        and technological establishment, having its principal place of business
        at 3 rue Michel-Ange, 75794 Paris cedex 16, France.
        
        Institut National de Recherche en Informatique et en Automatique -
        Inria, a public scientific and technological establishment, having its
        principal place of business at Domaine de Voluceau, Rocquencourt, BP
        105, 78153 Le Chesnay cedex, France.
        
        
            Preamble
        
        The purpose of this Free Software license agreement is to grant users
        the right to modify and redistribute the software governed by this
        license within the framework of an open source distribution model.
        
        The exercising of this right is conditional upon certain obligations for
        users so as to preserve this status for all subsequent redistributions.
        
        In consideration of access to the source code and the rights to copy,
        modify and redistribute granted by the license, users are provided only
        with a limited warranty and the software's author, the holder of the
        economic rights, and the successive licensors only have limited liability.
        
        In this respect, the risks associated with loading, using, modifying
        and/or developing or reproducing the software by the user are brought to
        the user's attention, given its Free Software status, which may make it
        complicated to use, with the result that its use is reserved for
        developers and experienced professionals having in-depth computer
        knowledge. Users are therefore encouraged to load and test the
        suitability of the software as regards their requirements in conditions
        enabling the security of their systems and/or data to be ensured and,
        more generally, to use and operate it in the same conditions of
        security. This Agreement may be freely reproduced and published,
        provided it is not altered, and that no provisions are either added or
        removed herefrom.
        
        This Agreement may apply to any or all software for which the holder of
        the economic rights decides to submit the use thereof to its provisions.
        
        Frequently asked questions can be found on the official website of the
        CeCILL licenses family (http://www.cecill.info/index.en.html) for any 
        necessary clarification.
        
Project-URL: Homepage, https://github.com/jcpassieux/pyxel
Project-URL: Bug Tracker, https://github.com/jcpassieux/pyxel/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: meshio
Requires-Dist: opencv-python
Requires-Dist: gmsh
Requires-Dist: scikit-image
Requires-Dist: interpylate

# pyxel

> **py**thon library for e**x**perimental mechanics using finite **el**ements

**pyxel** is an open-source Finite Element (FE) Digital Image/Volume Correlation (DIC/DVC) library for experimental mechanics applications. It is freely available for research and teaching.

<p align="center">
  <img src="https://raw.githubusercontent.com/jcpassieux/pyxel/master/pyxel.png" width="150" alt="pyxel logo">
</p>

In its present form, it is restricted to 2D-DIC and 3D-DVC. Stereo-DIC (SDIC) will be added later.

The gray level conservation problem is written in the physical space. It relies on camera models (which must be calibrated) and on a dedicated quadrature rule in the FE mesh space. For front-parallel camera settings, the implemented camera model is a simplified pinhole model, with 4 parameters in 2D (2 translations, 1 rotation and the focal length) and 7 parameters in 3D (focal length, 3 rotations and 3 translations). More complex camera models (including distortions) could easily be implemented within this framework (next update?).

The library natively includes linear and quadratic triangles, quadrilaterals, tetrahedra and hexahedra. Results can be exported in different formats, so that the measurements can be post-processed either with Matplotlib or with Paraview.

<p align="center">
  <img src="https://raw.githubusercontent.com/jcpassieux/pyxel/master/pyxel-figs.png" height="200" alt="pyxel example results">
</p>

## 0. Installation

- Install it from PyPI. The package is named `pyxel-dic`, but it is imported as `pyxel`:

  ```bash
  pip install pyxel-dic
  ```

  ```python
  import pyxel as px
  ```

- Alternatively, clone the git repository and install it in editable mode:

  ```bash
  git clone https://github.com/jcpassieux/pyxel.git
  cd pyxel
  pip install -e .
  ```

- Dependencies (`numpy`, `scipy`, `matplotlib`, `opencv-python`, `scikit-image`, `meshio`, `gmsh`) are installed automatically by `pip`. Python 3 is required.

## 1. Script files

- pyxel is a library: for each test case, a script file must be written.
- A set of tutorials is provided in the `./tests` folder to illustrate the main functionalities of the library.

## 2. About meshes

A Finite Element mesh is required for the displacement measurement. In pyxel, a mesh is entirely defined by two variables:

1. A Python dictionary for the elements. The key is the element type label (gmsh numbering) and the value is a numpy array of size `NE * NN`, where `NN` is the number of nodes of this element type and `NE` the number of elements. Example:

   ```python
   e = dict()
   e[3] = np.array([[n0, n1, n2, n3]])
   ```

2. A numpy array `n` for the node coordinates. Example:

   ```python
   n = np.array([[x0, y0], [x1, y1], ...])
   ```

Notes:

- `pyxel` is able to read and write all the mesh types supported by `meshio`.

## 3. Minimal sample code

To run a simple 2D-DIC analysis:

```python
import numpy as np
import pyxel as px

f = px.Image('img-0.tif').Load()
g = px.Image('img-1.tif').Load()
roi = np.array([[100, 100], [500, 500]])
m, cam = px.MeshFromROI(roi, 50, typel=3)
U, res = px.Correlate(f, g, m, cam)
```

## 4. Output files

Results can be post-processed directly with Matplotlib:

```python
m.PlotContourDispl(U, s=30)
```

A more convenient way (especially in DVC) is to use [Paraview](https://www.paraview.org):

```python
m.VTKSol('vtufile', U)
```

## 5. Terms of use

This program is free software: you can redistribute it and/or modify it. It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY.

**pyxel** is distributed under the terms of the [CeCILL](https://cecill.info) license, a French free software license agreement in the spirit of the GNU GPL.

## 6. Dependencies

`numpy`, `scipy`, `matplotlib`, `opencv-python`, `scikit-image`, `meshio`, `gmsh`

## References

Jean-Charles Passieux, Robin Bouclier. **Classic and Inverse Compositional Gauss-Newton in Global DIC**. *International Journal for Numerical Methods in Engineering*, 119(6), p. 453-468, 2019.

Jean-Charles Passieux. **pyxel, an open-source FE-DIC library**. *Zenodo*. [doi:10.5281/zenodo.4654018](http://doi.org/10.5281/zenodo.4654018)

### How to cite

```bibtex
@article{passieux2019classic,
  author  = {Passieux, Jean-Charles and Bouclier, Robin},
  title   = {Classic and Inverse Compositional Gauss-Newton in Global DIC},
  journal = {International Journal for Numerical Methods in Engineering},
  volume  = {119},
  number  = {6},
  pages   = {453--468},
  year    = {2019}
}

@software{passieux_pyxel,
  author = {Passieux, Jean-Charles},
  title  = {pyxel, an open-source FE-DIC library},
  doi    = {10.5281/zenodo.4654018},
  publisher = {Zenodo}
}
```
