Metadata-Version: 2.1
Name: impy-array
Version: 2.2.5
Summary: Speed up coding/extending image analysis in Python.
Project-URL: Download, https://github.com/hanjinliu/impy
Author-email: Hanjin Liu <liuhanjin-sc@g.ecc.u-tokyo.ac.jp>
License: BSD 3-Clause License
        
        Copyright (c) 2021, hanjinliu
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.8
Requires-Dist: dask>=2021.6.0
Requires-Dist: napari>=0.4.17
Requires-Dist: numpy>=1.22
Requires-Dist: pandas>=1.3
Requires-Dist: scikit-image>=0.20.0
Provides-Extra: all
Requires-Dist: mrcfile; extra == 'all'
Requires-Dist: zarr; extra == 'all'
Provides-Extra: mrc
Requires-Dist: mrcfile; extra == 'mrc'
Provides-Extra: zarr
Requires-Dist: zarr; extra == 'zarr'
Description-Content-Type: text/markdown

[![Downloads](https://pepy.tech/badge/impy-array/month)](https://pepy.tech/project/impy-array)
[![PyPI version](https://badge.fury.io/py/impy-array.svg)](https://badge.fury.io/py/impy-array)

# A numpy extension for efficient and powerful image analysis workflow

`impy` is an all-in-one image analysis library, equipped with parallel processing, GPU support, GUI based tools and so on.

The core array, `ImgArray`, is a subclass of `numpy.ndarray`, tagged with information such as 

- image axes
- scale of each axis
- directory of the original image
- and other image metadata

## Documentation

Documentation is available [here](https://hanjinliu.github.io/impy/).

## Installation

- use pip

```
pip install impy-array
```

- from source

```
git clone https://github.com/hanjinliu/impy
```

### Code as fast as you speak

Almost all the functions, such as filtering, deconvolution, labeling, single molecule detection, and even those pure `numpy` functions, are aware of image metadata. They "know" which dimension corresponds to `"z"` axis, which axes they should iterate along or where to save the image. As a result, **your code will be very concise**:

```python
import impy as ip
import numpy as np

img = ip.imread("path/to/image")       # Read images with metadata.
img["z=3;t=0"].imshow()                # Plot image slice at z=3 and t=0.
img_fil = img.gaussian_filter(sigma=2) # Paralell batch denoising. No more for loop!
img_prj = np.max(img_fil, axis="z")    # Z-projection (numpy is aware of image axes!).
img_prj.imsave(f"Max-{img.name}")      # Save in the same place. Don't spend time on searching for the directory!
```

### Supported file formats

`impy` automatically chooses proper reader/writer according to the extension.

- Tiff file (".tif", ".tiff")
- MRC file (".mrc", ".rec", ".st", ".map", ".map.gz")
- Zarr file (".zarr")
- Other image file (".png", ".jpg")

### Switch between CPU and GPU

`impy` can internally switches the functions between `numpy` and `cupy`.
You can use GPU for calculation very easily.

```python
img.gaussian_filter()  # <- CPU
with ip.use("cupy"):
    img.gaussian_filter()  # <- GPU
ip.Const["RESOURCE"] = "cupy"  # <- globally use GPU
```

### Seamless interface between `napari`

[napari](https://github.com/napari/napari) is an interactive viewer for multi-dimensional images. `impy` has a **simple and efficient interface** with it, via the object `ip.gui`. Since `ImgArray` is tagged with image metadata, you don't have to care about axes or scales. Just run 

```python
ip.gui.add(img)
```

### Extend your function for batch processing

Already have a function for `numpy` and `scipy`? Decorate it with `@ip.bind`

```python
@ip.bind
def imfilter(img, param=None):
    # Your function here.
    # Do something on a 2D or 3D image and return image, scalar or labels
    return out
```

and it's ready for batch processing!

```python
img.imfilter(param=1.0)
```

### Command line usage

`impy` also supports command line based image analysis. All method of `ImgArray` is available
from commad line, such as

```powershell
impy path/to/image.tif ./output.tif --method gaussian_filter --sigma 2.0
```

which is equivalent to

```python
import impy as ip
img = ip.imread("path/to/image.tif")
out = img.gaussian_filter(sigma=2.0)
out.imsave("./output.tif")
```

For more complex procedure, it is possible to send image directly to `IPython`

```
impy path/to/image.tif -i
```
```python
thr = img.gaussian_filter().threshold()
```
