# Getting started

## Installation

From PyPI:

```bash
pip install dpivsoft
```

Or from source:

```bash
git clone https://gitlab.com/jacabello/dpivsoft_python.git
cd dpivsoft_python
pip install .
```

Requirements: **Python ≥ 3.12**. The CPU implementation works out of the box.
GPU processing additionally needs an **OpenCL runtime** for your hardware —
any vendor works (AMD, Intel, NVIDIA drivers, or Mesa's *rusticl* on Linux);
there is no CUDA dependency. The GPU path runs the exact same algorithm as the
CPU path, roughly two orders of magnitude faster.

## A first PIV run (CPU)

The package can generate its own synthetic test images, so no experimental
data is needed to try it:

```python
import dpivsoft.DPIV as DPIV
import dpivsoft.SyIm as SyIm
from dpivsoft.Classes import Parameters

SyIm.Analytic_Syntetic("Images", "Test_Img_")        # synthetic image pair

Parameters.readParameters("simple_tutorial_parameters.yaml")  # or set attributes

Img1, Img2 = DPIV.load_images("Images/Test_Img_1.png",
                              "Images/Test_Img_2.png")
x, y, u, v = DPIV.processing(Img1, Img2)

DPIV.save(x, y, u, v, "result", 'openpiv')           # openpiv-compatible ASCII
```

All processing options (window sizes, grid, iterations, validation thresholds)
live in the global {class}`~dpivsoft.Classes.Parameters` class — set them as
attributes or load a YAML file; the parameters are explained on the
[PIV algorithm page](piv_algorithm.md#8-parameters).

## The same run on the GPU

Three set-up calls (once per session), then a processing loop:

```python
import dpivsoft.Cl_DPIV as Cl_DPIV
from dpivsoft.Classes import GPU

thr = Cl_DPIV.select_Platform("selection")   # interactive list; or an index, e.g. 0
Cl_DPIV.compile_Kernels(thr)                 # once per device
Cl_DPIV.initialization(width, height, thr)   # re-run if image size / parameters change

GPU.img1.set(Img1)                           # upload the first pair
GPU.img2.set(Img2)

Cl_DPIV.processing(next_img1_name, next_img2_name, thr)

x, y = GPU.x2.get(), GPU.y2.get()            # results back to NumPy
u, v = GPU.u2_f.get(), GPU.v2_f.get()        # final (median-filtered) field
```

Note the idiom: {func}`~dpivsoft.Cl_DPIV.processing` takes the file names of
the **next** image pair, so disk I/O overlaps with GPU compute when processing
a sequence — see the [OpenCL implementation page](opencl_implementation.md#7-hiding-the-file-io)
for details and a full loop.

## Tutorials

Runnable, commented end-to-end scripts live in `dpivsoft/Examples/` in the
repository. None of them require experimental data: images are synthesized in
place or downloaded on first run.

| script | covers |
|---|---|
| `simple_tutorial.py` | synthetic images → CPU PIV → GPU PIV → saving/plotting |
| `stereo_tutorial.py` | full stereo pipeline: calibration GUI, PIV per camera, Soloff 3C reconstruction, optional Δz self-calibration (downloads the PIV Challenge case E dataset, ~197 MB) |
| `forces_tutorial.py` | force estimation with the vortical impulse method |
| `mesh_tutorial.py` | FEM mesh + auxiliary potentials for the projection force method |
| `performance.py` | CPU vs GPU benchmark |

## Where to go next

- **How the PIV works** — [The PIV algorithm](piv_algorithm.md) and
  [The OpenCL implementation](opencl_implementation.md).
- **Stereo (3-component) PIV** — the practical
  [calibration workflow](stereo_workflow.md), and the
  [theory page](stereo_calibration_mapping.md) behind it.
- **Forces from PIV fields** — [Force estimation](forces_theory.md).
- **Every function's signature and docstring** — the API reference section in
  the sidebar.