Skip to content

Commit

Permalink
Update doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@paugier
paugier committed May 30, 2024
1 parent 134c874 commit 5c4f238
Show file tree
Hide file tree
Showing 8 changed files with 111 additions and 140 deletions.
9 changes: 5 additions & 4 deletions CITATION.cff
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,11 @@ cff-version: 1.2.0
message: If you use this software, please cite it using these metadata.
title: "Fluidimage: a Python framework to study flows from images"
abstract: |
Image processing is a common method in fluid mechanics, with various algorithms such
as Particle Image Velocimetry (PIV) or Light Induced Fluorescence (LIF) used to
compute velocity, vorticity, concentration or temperature fields. Fluidimage is a
Python framework to process images of fluids and analyze the results.
Fluid mechanics experimental studies are often based on image processing,
with various algorithms such as Particle Image Velocimetry (PIV) or
Light Induced Fluorescence (LIF) used to compute velocity, vorticity, concentration
or temperature fields. Fluidimage is a free and open-source Python framework
to process images of fluids and analyse the resulting fields.
authors:

- family-names: Augier
Expand Down
31 changes: 15 additions & 16 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,27 +1,26 @@
# How to contribute to FluidDyn and fluidimage

Thank you for considering contributing to FluidDyn. FluidDyn is a
community-driven project. It's people like you that make FluidDyn useful and
successful. There are many ways to contribute, from writing tutorials or
examples, improvements to the documentation, submitting bug reports and feature
requests, or even writing code which can be incorporated into FluidDyn for
everyone to use. (paragraph shamelessly taken and adapted from the MetPy
project!)
Thank you for considering contributing to FluidDyn. FluidDyn is a community-driven
project. It's people like you that make FluidDyn useful and successful. There are many
ways to contribute, from writing tutorials or examples, improvements to the
documentation, submitting bug reports and feature requests, or even writing code which
can be incorporated into FluidDyn for everyone to use. (paragraph shamelessly taken and
adapted from the MetPy project!)

## Reporting Issues

When opening an issue to report a problem
(<https://foss.heptapod.net/fluiddyn/fluidimage/issues>), please try to provide a
minimal code example that reproduces the issue along with details of the system
you are using. You can copy-paste the output of the command `fluidinfo -v`
(<https://foss.heptapod.net/fluiddyn/fluidimage/issues>), please try to provide a minimal
code example that reproduces the issue along with details of the system you are using.
You can copy-paste the output of the command `fluidinfo -v`
([Github gists](https://gist.github.com/) are good for that!).

## Development process

For FluidDyn, we use the revision control software Mercurial and our main
repositories are hosted here: <https://foss.heptapod.net/fluiddyn>.
For FluidDyn, we use the revision control software Mercurial and our main repositories
are hosted here: <https://foss.heptapod.net/fluiddyn>.

Please read our documentation on [developer
essentials](https://fluiddyn.readthedocs.io/en/latest/advice_developers.html),
and especially on [setting up
Mercurial](https://fluiddyn.readthedocs.io/en/latest/mercurial_heptapod.html).
Please read our documentation on
[developer essentials](https://fluiddyn.readthedocs.io/en/latest/advice_developers.html),
and especially on
[setting up Mercurial](https://fluiddyn.readthedocs.io/en/latest/mercurial_heptapod.html).
57 changes: 35 additions & 22 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,46 +8,59 @@
[![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)
[![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)

FluidImage is a libre Python framework for scientific processing of large series of
images.
<!-- start description -->

FluidImage is a free and open-source Python framework to process images of fluids (in
particular with [PIV]), and analyse the resulting fields.

**Documentation:** <http://fluidimage.readthedocs.org>

Image processing for fluid mechanics is highly dominated by proprietary tools. Such tools
are not ideal when you want to understand and tweak the processes and/or to use clusters.
With the improvement of the open-source tools for scientific computing and collaborative
development, one can think it is possible to build together a good library/toolkit
specialized in image processing for fluid mechanics. This is our project with FluidImage.
Image processing for fluid mechanics is still dominated by proprietary tools. Such tools
are not ideal when you want to understand and tweak the algorithms and/or to use
clusters. There are also good and useful PIV software ([PIVlab], [UVmat]) written in
Matlab, which is itself proprietary.

With the improvement of the Python numerical ecosystem and of tools for collaborative
development, one can think it is possible to build together a good community-driven
library/toolkit specialized in image processing for fluid mechanics. This is our project
with FluidImage. Fluidimage can be thought as a partial rewrite in Python of [UVmat] with
a focus on performance and usability. Moreover, we try to integrate good ideas taken from
[OpenPIV], [PIVlab] and [PIVmat].

This package is young but already good enough to be used "in production" to
This package is quite young but can be used to

- display and pre-process images,

- compute displacement or velocity fields with
[Particle Image Velocimetry](<https://en.wikipedia.org/wiki/Particle_image_velocimetry%20(PIV)>)
(PIV, i.e. displacements of pattern obtained by correlations of cropped images) and
- compute displacement or velocity fields with Particle Image Velocimetry ([PIV], i.e.
displacements of pattern obtained by correlations of cropped images),
Background-Oriented Schlieren
([BOS](https://en.wikipedia.org/wiki/Background-oriented_schlieren_technique)) and
[optical flow](https://en.wikipedia.org/wiki/Optical_flow),

- analyze and display PIV fields.

We want to make FluidImage easy (useful documentation, easy installation, usable with
scripts and GUI in Qt), reliable (with good
We want to make FluidImage easy (useful documentation, easy installation, good API,
usable with simple scripts and simple graphical user interfaces), reliable (with good
[unittests](https://codecov.io/gh/fluiddyn/fluidimage/)) and very efficient, in
particular when the number of images to process becomes large. Thus we want FluidImage to
be able to run efficiently and easily on a personal computer and on big clusters. The
efficiency is achieved by using
particular when the number of images is large. Thus we want FluidImage to be able to run
efficiently and easily on a personal computer and on big clusters. The efficiency is
achieved by using

- a framework for asynchronous computations (currently, we use
[Trio](https://trio.readthedocs.io) + multiprocessing, and in the long term we want to
be able to plug FluidImage to distributed computational systems like
[Dask](http://dask.pydata.org), [Spark](https://spark.apache.org/) or
[Storm](http://storm.apache.org/)),
[Trio](https://trio.readthedocs.io)) and an associated API to define "topologies" of
parallel computations.

- the available cores of the central processing units (CPU) and the available graphics
processing units (GPU),
- parallelism to efficiently use the available cores of the Central Processing Units
(CPU),

- good profiling and efficient and specialized algorithms,

- cutting-edge tools for fast computations with Python (in particular
[Pythran](https://pythran.readthedocs.io) through
[Transonic](https://transonic.readthedocs.io)).

[openpiv]: http://www.openpiv.net/
[piv]: https://en.wikipedia.org/wiki/Particle_image_velocimetry%20(PIV)
[pivlab]: https://pivlab.blogspot.com/p/what-is-pivlab.html
[pivmat]: http://www.fast.u-psud.fr/pivmat/
[uvmat]: http://servforge.legi.grenoble-inp.fr/projects/soft-uvmat/wiki/UvmatHelp
3 changes: 3 additions & 0 deletions doc/Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -162,3 +162,6 @@ zip: html

open_html: html
firefox _build/html/index.html

format:
mdformat *.md
60 changes: 28 additions & 32 deletions doc/build-from-source.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,7 @@ To build Fluidimage from source, ones needs:

- A decent amount of RAM (at least few GB available).

- A C++ compiler fully compliant with the C++-11 standard (currently not Intel
compilers)
- A C++ compiler fully compliant with the C++-11 standard (currently not Intel compilers)

## Get the source

Expand All @@ -18,8 +17,8 @@ Mercurial extensions like [Evolve] and [Topic]. The main repository is hosted
[here](https://foss.heptapod.net/fluiddyn/fluidimage) in
[Heptapod](https://heptapod.net/).

There are other ways to get the source but we are going here to assume that you
can install [Mercurial]. It can be useful when working with Fluidimage source to
There are other ways to get the source but we are going here to assume that you can
install [Mercurial]. It can be useful when working with Fluidimage source to
[fully setup Mercurial with these extensions and learn a bit of Mercurial](http://fluiddyn.readthedocs.org/en/latest/mercurial_heptapod.html).
Then, the Fluidimage repository can be cloned with

Expand Down Expand Up @@ -67,9 +66,9 @@ can check that everything goes well.
```

Moreover, the build (which uses [Meson]) can be controlled through environment
variables (for the C++ compilation) and options. The particular build options for
Fluidimage are defined in the file `meson.options` which contains:
Moreover, the build (which uses [Meson]) can be controlled through environment variables
(for the C++ compilation) and options. The particular build options for Fluidimage are
defined in the file `meson.options` which contains:

```{literalinclude} ../meson.options
```
Expand Down Expand Up @@ -182,27 +181,26 @@ Let us first present the tools used for Fluidimage development.

- [Meson] is an open source build system (in particular used by Scipy),

- [Nox] is a command-line tool that automates testing in multiple Python
environments,
- [Nox] is a command-line tool that automates testing in multiple Python environments,

- [Pytest] is the most popular testing framework for Python,

- [pip] is the official package installer for Python,

- [Pythran] is an ahead of time compiler for a subset of the Python language, with
a focus on scientific computing,
- [Pythran] is an ahead of time compiler for a subset of the Python language, with a
focus on scientific computing,

- [Transonic] is a pure Python package to accelerate modern Python-Numpy code with
different accelerators (in particular Pythran).

Fluidimage is built with [Meson]. We use [PDM] for Fluidimage development.
[Pytest] and [Nox] are used for testing. We use [Pythran] through [Transonic] to
accelerate some numerical kernels written in Python.
Fluidimage is built with [Meson]. We use [PDM] for Fluidimage development. [Pytest] and
[Nox] are used for testing. We use [Pythran] through [Transonic] to accelerate some
numerical kernels written in Python.

#### Standard Python from Python.org

We present here how one can build Fluidimage from source like the main developers
and users.
We present here how one can build Fluidimage from source like the main developers and
users.

##### Install PDM

Expand All @@ -215,19 +213,17 @@ python3 -m pip install pipx
pipx install pdm -U
```

Installing in editable mode is a bit particular with Meson, since editable
installations are incompatible with isolated builds, meaning that all build
dependencies have to be installed in the main virtual environment! Fortunatelly,
it's not too difficult with [PDM]. From the root directory of the repository, just
run:
Installing in editable mode is a bit particular with Meson, since editable installations
are incompatible with isolated builds, meaning that all build dependencies have to be
installed in the main virtual environment! Fortunatelly, it's not too difficult with
[PDM]. From the root directory of the repository, just run:

```sh
pdm install --no-self
```

This command creates a virtual environment and installs all build and runtime
dependencies. You can then activate this environment and build/install Fluidimage
with:
dependencies. You can then activate this environment and build/install Fluidimage with:

```sh
. .venv/bin/activate
Expand All @@ -236,8 +232,8 @@ pip install -e . -v --no-build-isolation --no-deps

### Conda-based Python with conda-forge and Pixi

One can use [Pixi] to setup a developer environment based on [conda-forge] and
compile from source. From the root directory of Fluidimage repository, just run:
One can use [Pixi] to setup a developer environment based on [conda-forge] and compile
from source. From the root directory of Fluidimage repository, just run:

```sh
pixi run install-editable
Expand All @@ -249,15 +245,15 @@ Then, `pip` is available and previous commands should work.

### Run the tests

You can run some unit tests by running `make tests`. Alternatively, you can also
run `pytest` from the root directory or from any of the source directories.
You can run some unit tests by running `make tests`. Alternatively, you can also run
`pytest` from the root directory or from any of the source directories.

(pythranrc)=

### About using Pythran to compile functions

When developing with Pythran, it can be useful to have a `~/.pythranrc` file, with
for example something like (see
When developing with Pythran, it can be useful to have a `~/.pythranrc` file, with for
example something like (see
[the dedicated section in Pythran documentation](https://pythran.readthedocs.io/en/latest/MANUAL.html#customizing-your-pythranrc)):

```sh
Expand All @@ -271,9 +267,9 @@ CC=clang

```

Note however, that Fluidimage build does not take into account this file! Instead
there is a build option `pythran-complex-hook` and one can use environment
variables to change the C++ compilation (performed with [Meson]).
Note however, that Fluidimage build does not take into account this file! Instead there
is a build option `pythran-complex-hook` and one can use environment variables to change
the C++ compilation (performed with [Meson]).

### Set the MESONPY_EDITABLE_VERBOSE mode

Expand Down
6 changes: 4 additions & 2 deletions doc/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

# Fluidimage documentation

FluidImage is a libre Python framework for scientific processing of
large series of images.
FluidImage is a free and open-source Python framework to process images of fluids (in
particular with [PIV]), and analyse the resulting fields.

```{toctree}
---
Expand Down Expand Up @@ -44,3 +44,5 @@ for_dev
- {ref}`genindex`
- {ref}`modindex`
- {ref}`search`

[piv]: https://en.wikipedia.org/wiki/Particle_image_velocimetry%20(PIV)
32 changes: 16 additions & 16 deletions doc/install.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,12 @@
# Installation

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

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

## Install with pip

Expand All @@ -28,19 +27,18 @@ pip install fluidimage

### Optional dependencies

Fluidimage has 2 sets of optional dependencies, which can be installed with
commands like `pip install fluidimage[opencv]` or
`pip install fluidimage[opencv, pims]`:
Fluidimage has 2 sets of optional dependencies, which can be installed with commands like
`pip install fluidimage[opencv]` or `pip install fluidimage[opencv, pims]`:

- `opencv`: [OpenCV](https://opencv.org/) can be used for some algorithms,
- `pims`: [pims: Python Image Sequence](https://github.com/soft-matter/pims) is
used to read `.cine` files.
- `pims`: [pims: Python Image Sequence](https://github.com/soft-matter/pims) is used to
read `.cine` files.

## Install the conda-forge packages with conda or mamba
## Install the conda-forge package with conda or mamba

We recommend installing `conda` and `mamba` (using the \[conda-forge\] channel)
with the [miniforge installer](https://github.com/conda-forge/miniforge). Then,
one can run:
We recommend installing `conda` and `mamba` with the
[miniforge installer](https://github.com/conda-forge/miniforge) so that the installed
packages will be uploaded from the [conda-forge] channel. Then, one can run:

```sh
mamba install fluidimage
Expand All @@ -53,3 +51,5 @@ mamba create -n env_fluidimage fluidimage
```

The environment can then be activated with `conda activate env_fluidimage`.

[conda-forge]: https://conda-forge.org/
Loading

0 comments on commit 5c4f238

Please sign in to comment.