diff --git a/CITATION.cff b/CITATION.cff index 61c21dd..56df77f 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 00ed1fc..11d12f7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 -(), 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` +(), 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: . +For FluidDyn, we use the revision control software Mercurial and our main repositories +are hosted here: . -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). diff --git a/README.md b/README.md index 5641caf..8cc6c36 100644 --- a/README.md +++ b/README.md @@ -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. + + +FluidImage is a free and open-source Python framework to process images of fluids (in +particular with [PIV]), and analyse the resulting fields. **Documentation:** -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]() - (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 diff --git a/doc/Makefile b/doc/Makefile index 9ac2dc8..7aeac71 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -162,3 +162,6 @@ zip: html open_html: html firefox _build/html/index.html + +format: + mdformat *.md diff --git a/doc/build-from-source.md b/doc/build-from-source.md index f046941..7f31561 100644 --- a/doc/build-from-source.md +++ b/doc/build-from-source.md @@ -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 @@ -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 @@ -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 ``` @@ -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 @@ -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 @@ -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 @@ -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 @@ -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 diff --git a/doc/index.md b/doc/index.md index 11c64a2..406b831 100644 --- a/doc/index.md +++ b/doc/index.md @@ -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} --- @@ -44,3 +44,5 @@ for_dev - {ref}`genindex` - {ref}`modindex` - {ref}`search` + +[piv]: https://en.wikipedia.org/wiki/Particle_image_velocimetry%20(PIV) diff --git a/doc/install.md b/doc/install.md index 8d7eb89..79273bd 100644 --- a/doc/install.md +++ b/doc/install.md @@ -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 @@ -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 @@ -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/ diff --git a/doc/overview.md b/doc/overview.md index 5c7a079..b084b13 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -1,50 +1,7 @@ # Overview -FluidImage is a libre Python framework for scientific processing of -large series of images. - -**Documentation:** - -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. - -This package is young but already good enough to be used "in -production" 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 [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 -[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 - -- 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/)), - -- the available cores of the central processing units (CPU) and the - available graphics processing units (GPU), - -- good profiling and efficient and specialized algorithms, - -- cutting-edge tools for fast computations with Python (in particular - [Pythran](https://pythonhosted.org/pythran/)). +```{include} ../README.md +--- +start-after: +--- +```