python-FloatImg/README.md

# python-FloatImg

A pythonesque binding to FloatImg library available at https://git.tetalab.org/tTh/FloatImg

python-FloatImg requires a Python 3 implementation (tested with 3.6.9).

Most function are wrapped into a similar api, sometime with a more consistent naming and an object-oriented approach.

Color values are specified using triplets of float values, like (128.5, 34.234, 242.23).

## Installation

python-FloatImg requires a shared object file (.so) that is not yet officialy available from FloatImg.

The file `floatimg/settings.py` contains the path to the .so file and the encoding of path characters.

## Usage

```python
import floatimg
```

The FloatImg class encapsulate core and file functionnalities of FloatImg library. Instances are created with functions from the module.

Colors are tuple of three elements `(r, g, b)`.

### Image creation

`FloatImg` has two class methods to create an image.

```python
img = floatimg.create(640, 480, floatimg.RGB)
```
Or use the `create_rgb` shortcut:

```python
img = floatimg.create_rgb(640, 480)
```

Note that calling the `destroy` method of the instance is not necessary as it will be called automatically at instance destruction.

Or completely duplicate an existing image:

```python
# without copying data
new_img = img.clone()

# with copying data
new_img = img.clone(True)
```

### Basic pixel operations

```python
# Get pixel value
color = (r, g, b) = img.get(x, y)

# Set pixel value
img.put(x, y, (r, g, b))

# Reset all pixels to zero.
img.clear()

# Copy pixels to another image of the same format
img.copy_data(another_img)
```

### File operations

#### Raw dump files

```python
# Dump image to file
img.dump(path)

# Restore image data from a dump file
img.load(path)

# Create a new image from a dump file
img = floatimg.create_from_dump(path)

# Get dump metadata (TODO create a FileInfo named tuple)
witdh, height, img_type = floatimg.fileinfos(path)
```

#### External formats

```python
# export supports the following extentions : .fimg, .png, .tiff, .pnm, .fits
# save as png
img.export("test.png")

# create an image instance from png file
img = floatimg.create_from_png("test.png")

# load pixel data from png file in an existing instance. size and type have to be compatible
img.load_png("test.png")
```


## Operators

```python
# addition
res_img = img + img2

# substraction
res_img = img - img2

# multiplication
res_img = img * img2

# min value per color channel
res_img = img.min(img2)

# max value per color channel
res_img = img.max(img2)

```

## Contrast operations

Contrast types are defined in the Contrast enumeration:

```
floatimg.Contrast.SQRT
floatimg.Contrast.POW2
floatimg.Contrast.COS01
floatimg.Contrast.COS010
```

To apply contrast:

```
# Return a new image
res = img.contrast(value, floatimg.Contrast.SQRT)

# set contrast in-place
img.contrast(value, floatimg.Contrast.SQRT, True)
```



## Development

### Run tests

Install development requirements (you may add --user if not in a virtual environment or not in system-wide install):

```
pip install -r requirements-devel.txt
```

Ensure `floatimg` containing path is in the `PYTHONPATH`, this will run the tests and show a coverage report:

```
pytest --cov=floatimg tests/*
```

### Status

The goal is not to bind all the functions but essential ones too build a front-end with python-tkinter. 

#### Done

 - lib/fimg-core.c
 - lib/fimg-file.c
 - lib/operator.c
 - funcs/exporter.c
 - funcs/fimg-png.c

#### Partial

 - lib/fimg-math.c