Skip to content

Commit aab0fc9

Browse files
paugierpaugier
committed
Merge branch 'topic/default/README' into 'branch/default'
Improve README and doc Closes #46 and #47 See merge request fluiddyn/fluidimage!121
2 parents 268bf91 + cf0f9d0 commit aab0fc9

File tree

3 files changed

+101
-8
lines changed

3 files changed

+101
-8
lines changed

‎README.md‎

Lines changed: 40 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,12 @@
33
[![Latest version](https://img.shields.io/pypi/v/fluidimage.svg)](https://pypi.python.org/pypi/fluidimage/)
44
![Supported Python versions](https://img.shields.io/pypi/pyversions/fluidimage.svg)
55
[![Documentation status](https://readthedocs.org/projects/fluidimage/badge/?version=latest)](http://fluidimage.readthedocs.org)
6+
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
67
[![Code coverage](https://codecov.io/gh/fluiddyn/fluidimage/branch/branch%2Fdefault/graph/badge.svg)](https://codecov.io/gh/fluiddyn/fluidimage/branch/branch%2Fdefault/)
78
[![Heptapod CI](https://foss.heptapod.net/fluiddyn/fluidimage/badges/branch/default/pipeline.svg)](https://foss.heptapod.net/fluiddyn/fluidimage/-/pipelines)
89
[![Github Actions Linux](https://github.com/fluiddyn/fluidimage/actions/workflows/ci-linux.yml/badge.svg?branch=branch/default)](https://github.com/fluiddyn/fluidimage/actions/workflows/ci-linux.yml)
910
[![Github Actions Pixi](https://github.com/fluiddyn/fluidimage/actions/workflows/ci-pixi.yml/badge.svg?branch=branch/default)](https://github.com/fluiddyn/fluidimage/actions/workflows/ci-pixi.yml)
1011

11-
<!-- start description -->
12-
1312
FluidImage is a free and open-source Python framework to process images of fluids (in
1413
particular with [PIV]), and analyse the resulting fields.
1514

@@ -59,8 +58,47 @@ achieved by using
5958
[Pythran](https://pythran.readthedocs.io) through
6059
[Transonic](https://transonic.readthedocs.io)).
6160

61+
## Installation and setup
62+
63+
Fluidimage can be installed from
64+
[wheels and sdist available on PyPI](https://pypi.python.org/pypi/fluidimage/)
65+
with tools like pip, [UV], [PDM], ... or from conda-forge packages (for example
66+
available on https://prefix.dev/channels/conda-forge/packages/fluidimage) with
67+
tools like conda (installed with [Miniforge]) or [Pixi].
68+
69+
In some cases, Fluidimage will require that the environment variable
70+
`OMP_NUM_THREADS` is set to `1`. With a POSIX shell like Bash, it can be done with
71+
`export OMP_NUM_THREADS=1`.
72+
73+
For more details, see
74+
[the installation page in the documentation](https://fluidimage.readthedocs.io/en/latest/install.html).
75+
76+
## Citation
77+
78+
If you use Fluidimage to produce scientific articles, please cite
79+
[our metapaper presenting the FluidDyn project](https://openresearchsoftware.metajnl.com/articles/10.5334/jors.237/):
80+
81+
```bibtex
82+
83+
@article{fluiddyn,
84+
doi = {10.5334/jors.237},
85+
year = {2019},
86+
publisher = {Ubiquity Press, Ltd.},
87+
volume = {7},
88+
author = {Pierre Augier and Ashwin Vishnu Mohanan and Cyrille Bonamy},
89+
title = {{FluidDyn}: A Python Open-Source Framework for Research and Teaching in Fluid Dynamics
90+
by Simulations, Experiments and Data Processing},
91+
journal = {Journal of Open Research Software}
92+
}
93+
94+
```
95+
6296
[openpiv]: http://www.openpiv.net/
6397
[piv]: https://en.wikipedia.org/wiki/Particle_image_velocimetry
6498
[pivlab]: https://pivlab.blogspot.com/p/what-is-pivlab.html
6599
[pivmat]: http://www.fast.u-psud.fr/pivmat/
66100
[uvmat]: http://servforge.legi.grenoble-inp.fr/projects/soft-uvmat/wiki/UvmatHelp
101+
[miniforge]: https://github.com/conda-forge/miniforge
102+
[pixi]: https://pixi.sh
103+
[pdm]: https://pdm-project.org
104+
[uv]: https://docs.astral.sh/uv/

‎doc/install.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,21 @@
11
# Installation
22

33
First, ensure that you have a recent Python installed, since Fluidimage requires Python
4-
\>= 3.9. Some issues regarding the installation of Python and Python packages are
4+
\>= 3.11. Some issues regarding the installation of Python and Python packages are
55
discussed in
66
[the main documentation of the Fluiddyn project](http://fluiddyn.readthedocs.org/en/latest/install.html).
77

88
Here, we describe installation methods that do not involve local compilation. One can
99
also install Fluidimage from source as described [here](./build-from-source.md).
1010

11+
```{note}
12+
13+
In some cases, Fluidimage will require that the environment variable
14+
`OMP_NUM_THREADS` is set to `1`. With a POSIX shell like Bash, it can be done with
15+
`export OMP_NUM_THREADS=1`.
16+
17+
```
18+
1119
## Install with pip
1220

1321
```{note}

‎doc/overview.md‎

Lines changed: 52 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,54 @@
11
# Overview
22

3-
```{include} ../README.md
4-
---
5-
start-after: <!-- start description -->
6-
---
7-
```
3+
FluidImage is a free and open-source Python framework to process images of fluids (in
4+
particular with [PIV]), and analyse the resulting fields.
5+
6+
Image processing for fluid mechanics is still dominated by proprietary tools. Such tools
7+
are not ideal when you want to understand and tweak the algorithms and/or to use
8+
clusters. There are also good and useful PIV software ([PIVlab], [UVmat]) written in
9+
Matlab, which is itself proprietary.
10+
11+
With the improvement of the Python numerical ecosystem and of tools for collaborative
12+
development, one can think it is possible to build together a good community-driven
13+
library/toolkit specialized in image processing for fluid mechanics. This is our project
14+
with FluidImage.
15+
16+
Fluidimage has now grown into a clean software reimplementing in modern Python algorithms
17+
and ideas taken from [UVmat], [OpenPIV], [PIVlab] and [PIVmat] with a focus on
18+
performance, usability and maintanability. However, Fluidimage is not restricted to
19+
Particle Image Velocimetry computations ([PIV], i.e. displacements of pattern obtained by
20+
correlations of cropped images) and can be used to
21+
22+
- display and pre-process images,
23+
24+
- compute displacement or velocity fields with PIV, Background-Oriented Schlieren
25+
([BOS](https://en.wikipedia.org/wiki/Background-oriented_schlieren_technique)) and
26+
[optical flow](https://en.wikipedia.org/wiki/Optical_flow),
27+
28+
- analyze and display vector and scalar fields.
29+
30+
We want to make FluidImage easy (useful documentation, easy installation, nice API,
31+
usable with simple scripts and few simple graphical user interfaces), reliable (with good
32+
[unittests](https://codecov.io/gh/fluiddyn/fluidimage/)) and very efficient, in
33+
particular when the number of images is large. Thus we want FluidImage to be able to run
34+
efficiently and easily on a personal computer and on big clusters. The efficiency is
35+
achieved by using
36+
37+
- a framework for asynchronous computations (currently, we use
38+
[Trio](https://trio.readthedocs.io)) and an associated API to define "topologies" of
39+
parallel computations.
40+
41+
- parallelism to efficiently use the available cores of the Central Processing Units
42+
(CPU),
43+
44+
- good profiling and efficient and specialized algorithms,
45+
46+
- cutting-edge tools for fast computations with Python (in particular
47+
[Pythran](https://pythran.readthedocs.io) through
48+
[Transonic](https://transonic.readthedocs.io)).
49+
50+
[openpiv]: http://www.openpiv.net/
51+
[piv]: https://en.wikipedia.org/wiki/Particle_image_velocimetry
52+
[pivlab]: https://pivlab.blogspot.com/p/what-is-pivlab.html
53+
[pivmat]: http://www.fast.u-psud.fr/pivmat/
54+
[uvmat]: http://servforge.legi.grenoble-inp.fr/projects/soft-uvmat/wiki/UvmatHelp

0 commit comments

Comments
 (0)