breaking changes: more pythonic api (still allowed because of the very begining state of the project

README.md

@@ -1,3 +1,121 @@
 # python-FloatImg
 
-A python binding to FloatImg library available at https://git.tetalab.org/tTh/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.
+
+## Usage
+
+The FloatImg class encapsulate core and file functionnalities of FloatImg library. Import if from the main module:
+
+```python
+import floatimg
+```
+
+### 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)
+```
+
+### Image manipulation
+
+#### Clear image
+
+Reset all pixels to zero.
+
+```python
+img.clear()
+```
+
+#### Copy pixels to another image
+
+```python
+img.copy_data(another_img)
+```
+
+#### Set pixel value
+
+```python
+img.put(x, y, (r, g, b))
+```
+
+#### Get pixel value
+
+```python
+color = (r, g, b) = img.get(x, y)
+```
+
+### File manipulation
+
+#### Dump image to file
+
+```python
+img.dump("/tmp/image_dump")
+```
+
+#### Restore image data from a dump file
+
+```python
+img.load("/tmp/image_dump")
+```
+
+#### Create a new image from a dump file
+
+```python
+img = floatimg.create_from_dump("/tmp/image_dump")
+```
+#### Get dump metadata
+
+TODO create a FileInfo named tuple.
+
+```python
+witdh, height, img_type = floatimg.fileinfos("/tmp/image_dump")
+```
+
+
+## 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/*
+```
+

floatimg/__init__.py

@@ -0,0 +1,6 @@
+"""Python Binding to FloatImg """
+
+# FloatImg class and static functions
+from floatimg.image import FloatImg, create, create_rgb, create_from_dump, GRAY, RGB, fileinfos
+
+__version__ = "0.0.1"

floatimg/image.py

@@ -0,0 +1,274 @@
+import ctypes as ct
+
+from floatimg.settings import LIB
+
+############################################################################################################
+# type constants
+GRAY = 1
+RGB = 3
+RGBA = 4
+RGBZ = 99
+
+############################################################################################################
+# Type mapping
+class C_FloatImg(ct.Structure):
+    """mapping to the C structure of FloatImg"""
+
+    pass
+
+
+C_FloatImg._fields_ = [
+    ("magic", ct.c_ulong),
+    ("width", ct.c_int),
+    ("height", ct.c_int),
+    ("type", ct.c_int),
+    ("fval", ct.c_float),
+    ("count", ct.c_int),
+    ("R", ct.POINTER(ct.c_float)),
+    ("G", ct.POINTER(ct.c_float)),
+    ("B", ct.POINTER(ct.c_float)),
+    ("A", ct.POINTER(ct.c_float)),
+    ("reserved", ct.c_int),
+]
+
+############################################################################################################
+# declaration of input / output types
+c_fimgcreate = LIB.fimg_create
+c_fimgcreate.argtypes = (ct.POINTER(C_FloatImg), ct.c_int, ct.c_int, ct.c_int)
+c_fimgcreate.restype = ct.c_int
+
+c_fimg_destroy = LIB.fimg_destroy
+c_fimg_destroy.argtypes = (ct.POINTER(C_FloatImg),)
+c_fimg_destroy.restype = ct.c_int
+
+c_fimg_clone = LIB.fimg_clone
+c_fimg_clone.argtypes = (ct.POINTER(C_FloatImg), ct.POINTER(C_FloatImg))
+c_fimg_clone.restype = ct.c_int
+
+c_fimg_copy_data = LIB.fimg_copy_data
+c_fimg_copy_data.argtypes = (ct.POINTER(C_FloatImg), ct.POINTER(C_FloatImg))
+c_fimg_copy_data.restype = ct.c_int
+
+c_fimg_type_is_valid = LIB.fimg_type_is_valid
+c_fimg_type_is_valid.argtypes = (ct.c_int,)
+c_fimg_copy_data.restype = ct.c_int
+
+c_fimg_str_type = LIB.fimg_str_type
+c_fimg_str_type.argtypes = (ct.c_int,)
+c_fimg_str_type.restype = ct.c_char_p
+
+c_fimg_clear = LIB.fimg_clear
+c_fimg_clear.argtypes = (ct.POINTER(C_FloatImg),)
+c_fimg_clear.restype = ct.c_int
+
+
+c_fimg_plot_rgb = LIB.fimg_plot_rgb
+c_fimg_plot_rgb.argtypes = (
+    ct.POINTER(C_FloatImg),
+    ct.c_int,
+    ct.c_int,
+    ct.c_float,
+    ct.c_float,
+    ct.c_float,
+)
+c_fimg_plot_rgb.restype = ct.c_int
+
+
+# int   fimg_get_rgb(FloatImg *head, int x, int y, float *rgb);
+c_fimg_get_rgb = LIB.fimg_get_rgb
+c_fimg_get_rgb.argtypes = (
+    ct.POINTER(C_FloatImg),
+    ct.c_int,
+    ct.c_int,
+    ct.POINTER(ct.c_float * 3),
+)
+c_fimg_get_rgb.restype = ct.c_int
+
+# int   fimg_put_rgb(FloatImg *head, int x, int y, float *rgb);
+c_fimg_put_rgb = LIB.fimg_put_rgb
+c_fimg_put_rgb.argtypes = (
+    ct.POINTER(C_FloatImg),
+    ct.c_int,
+    ct.c_int,
+    ct.POINTER(ct.c_float * 3),
+)
+c_fimg_put_rgb.restype = ct.c_int
+
+c_fimg_rgb_constant = LIB.fimg_rgb_constant
+c_fimg_rgb_constant.argtypes = (
+    ct.POINTER(C_FloatImg),
+    ct.c_float,
+    ct.c_float,
+    ct.c_float,
+)
+c_fimg_rgb_constant.restype = ct.c_int
+
+c_fimg_dump_to_file = LIB.fimg_dump_to_file
+c_fimg_dump_to_file.argtypes = (ct.POINTER(C_FloatImg), ct.c_char_p, ct.c_int)
+c_fimg_dump_to_file.restype = ct.c_int
+
+c_fimg_load_from_dump = LIB.fimg_load_from_dump
+c_fimg_load_from_dump.argtypes = (ct.c_char_p, ct.POINTER(C_FloatImg))
+c_fimg_load_from_dump.restype = ct.c_int
+
+c_fimg_fileinfos = LIB.fimg_fileinfos
+c_fimg_fileinfos.argtypes = (ct.c_char_p, ct.POINTER(ct.c_int * 3))
+c_fimg_fileinfos.restype = ct.c_int
+
+############################################################################################################
+class FloatImg:
+    """
+
+    Pythonic Object-Oriented encapsulation of floatimg library
+
+    :attr c_img: an instance of C_FloatImg structure
+    :attr c_img: an pointer to the c_img structure
+    """
+
+    # proxy attributes to the C_FloatImg structure
+    # TODO: now more about them
+    magic = property(lambda self: self.c_img.magic)
+    fval = property(lambda self: self.c_img.fval)
+    count = property(lambda self: self.c_img.count)
+
+    # oh yeah, really really sluggish access to pixels img.R[0].contents
+    # however, pixel data are not designed to be accessed this way
+    # R = property(
+    #     lambda self: pointer(self.c_img.contents.R)[: self.width * self.height]
+    # )
+
+    #######################################################################################################
+    def __init__(self, c_img):
+        self.c_img = c_img
+        self.width = c_img.width
+        self.height = c_img.height
+        self.type_id = c_img.type
+        # convenient pointer for later calls to C library
+        self.c_img_p = ct.pointer(c_img)
+
+    #######################################################################################################
+    def __str__(self):
+        return f"<{self.__class__.__name__} instance {id(self)} width={self.width} height={self.height} type={self.str_type}>"
+
+    #######################################################################################################
+    def destroy(self):
+        """destroy the underlying structure. automattically called at instance destruction"""
+        assert c_fimg_destroy(self.c_img) == 0
+
+    #######################################################################################################
+    def __del__(self):
+        self.destroy()
+
+    #######################################################################################################
+    def clear(self):
+        """clear data"""
+        assert c_fimg_clear(self.c_img_p) == 0
+
+    #######################################################################################################
+    def clone(self, copy_data=False):
+        """return a clone of the current instance"""
+        if copy_data:
+            flags = 1
+        else:
+            flags = 0
+        new_pic = C_FloatImg()
+        assert c_fimg_clone(self.c_img_p, ct.pointer(new_pic), flags) == 0
+        return FloatImg(new_pic)
+
+    #######################################################################################################
+    def copy_data(self, to_img):
+        assert c_fimg_copy_data(self.c_img_p, to_img.c_img_p) == 0
+
+    #######################################################################################################
+    @property
+    def str_type(self):
+        """return the type of the image as a string"""
+        return c_fimg_str_type(self.c_img.type).decode("utf-8")
+
+    #######################################################################################################
+    def fill(self, color):
+        assert c_fimg_rgb_constant(self.c_img_p, *color) == 0
+
+    #######################################################################################################
+    def get(self, x, y):
+        """get r,g,b triplet from a pixel"""
+        rgb = (ct.c_float * 3)()
+        assert c_fimg_get_rgb(self.c_img_p, x, y, ct.pointer(rgb)) == 0
+        return rgb[:3]
+
+    #######################################################################################################
+    def put(self, x, y, rgb):
+        """put r,g,b triplet to a pixel"""
+        # TODO may be a better way to create the array rather than iterating
+        c_rgb = (ct.c_float * 3)()
+        for i, c in enumerate(rgb):
+            c_rgb[i] = c
+        assert c_fimg_put_rgb(self.c_img_p, x, y, ct.pointer(c_rgb)) == 0
+
+    #######################################################################################################
+    def dump(self, fname):
+        """save data to a dump file"""
+        # TODO use system encoding instead of utf-8
+        assert (
+            c_fimg_dump_to_file(
+                self.c_img_p, ct.c_char_p(bytes(fname, encoding="utf8")), 0
+            )
+            == 0
+        )
+
+    #######################################################################################################
+    def load(self, fname):
+        """load data from a dump. size and type have to be compatible"""
+        assert (
+            c_fimg_load_from_dump(
+                ct.c_char_p(bytes(fname, encoding="utf8")), self.c_img_p
+            )
+            == 0
+        )
+
+    # TODO
+    # fimg_plot_rgb
+    # fimg_add_rgb
+
+    # export(fname, flags) : depending file extension, save to the correct format
+
+
+###########################################################################################################
+def fileinfos(fname):
+    """return witdh, height, img_type triplet read from a dump file"""
+    datas = (ct.c_int * 3)()
+    assert (
+        c_fimg_fileinfos(ct.c_char_p(bytes(fname, encoding="utf8")), ct.pointer(datas))
+        == 0
+    )
+    return datas[:3]
+
+
+###########################################################################################################
+def create(witdh, height, type_id):
+    """create an new FloatImg instance"""
+    assert type_is_valid(type_id)
+    img = C_FloatImg()
+    assert c_fimgcreate(ct.pointer(img), witdh, height, type_id) == 0
+    return FloatImg(img)
+
+
+###########################################################################################################
+def create_rgb(witdh, height):
+    """create a new rgb instance """
+    return create(witdh, height, RGB)
+
+
+###########################################################################################################
+def create_from_dump(fname):
+    """Create a new instance from a dump file"""
+    witdh, height, img_type = fileinfos(fname)
+    img = create(witdh, height, img_type)
+    img.load(fname)
+    return img
+
+
+###########################################################################################################
+def type_is_valid(type_id):
+    """return True if type_id is a valid one"""
+    return c_fimg_type_is_valid(type_id) == 1

floatimg/settings.py

@@ -0,0 +1,5 @@
+import ctypes
+
+# LIB = ctypes.cdll.LoadLibrary("../FloatImg/libfloatimg.so")
+
+LIB = ctypes.cdll.LoadLibrary("../FloatImg4PythonBinding/build/lib/libfloatimg.so")

requirements-devel.txt

@@ -0,0 +1,2 @@
+pytest
+pytest-cov

tests/basics.py

@@ -0,0 +1,106 @@
+"""test of core functions """
+
+import floatimg
+
+
+def test_create():
+    width = 640
+    height = 480
+    img = floatimg.create(width, height, floatimg.RGB)
+    assert img.width == width
+    assert img.height == height
+    assert img.type_id == floatimg.RGB
+
+    img = floatimg.create_rgb(width, height)
+
+    assert img.type_id == floatimg.RGB
+    # TODO inspect RVB
+
+
+def test_clone():
+    width = 5
+    height = 5
+    img = floatimg.create(width, height, floatimg.RGB)
+    img.fill((127.0, 127.0, 127.0))
+
+    # clone without copying pixel values
+    img2 = img.clone(False)
+    assert img.width == img2.width
+    assert img.height == img2.height
+    assert img.type_id == img2.type_id
+    # TODO inspect RVB and do pixel per pixel comparison
+    for y in range(height):
+        for x in range(width):
+            assert img.get(x, y) != img2.get(x, y)
+
+    img2 = img.clone(True)
+    assert img.width == img2.width
+    assert img.height == img2.height
+    assert img.type_id == img2.type_id
+    # TODO inspect RVB and do pixel per pixel comparison
+    for y in range(height):
+        for x in range(width):
+            assert img.get(x, y) == img2.get(x, y)
+
+
+def test_rgb_constant():
+    width = 5
+    height = 5
+    color = [127.0, 127.0, 127.0]
+    img = floatimg.create_rgb(width, height)
+    img.fill(color)
+    for y in range(height):
+        for x in range(width):
+            assert img.get(x, y) == color
+
+
+
+def test_copy_data():
+    width = 5
+    height = 5
+    color = [127.0, 127.0, 127.0]
+    img = floatimg.create_rgb(width, height)
+    img.fill(color)
+
+    img2 = floatimg.create_rgb(width, height)
+    img2.fill((64.0, 64.0, 64.0))
+
+    img.copy_data(img2)
+
+    for y in range(height):
+        for x in range(width):
+            assert img.get(x, y) == img2.get(x, y)
+
+
+def test_clear():
+    width, height = 5, 5
+    color = [127.0, 127.0, 127.0]
+    img = floatimg.create_rgb(width, height)
+    img.fill(color)
+    img.clear()
+    for y in range(height):
+        for x in range(width):
+            assert img.get(x, y) == [0.0, 0.0, 0.0]
+
+
+def test_str_type():
+    width, height = 5, 5
+    img = floatimg.create_rgb(width, height)
+    assert img.str_type == "rgb"
+
+
+def test__str__():
+    width, height = 5, 5
+    img = floatimg.create_rgb(width, height)
+    img_str = str(img)
+    assert " width=5 " in img_str
+    assert " height=5 " in img_str
+    assert " type=rgb>" in img_str
+
+
+def test_put_rgb():
+    width, height = 5, 5
+    img = floatimg.create_rgb(width, height)
+    assert img.get(0, 0) == [0.0, 0.0, 0.0]
+    img.put(0, 0, (127.0, 127.0, 127.0))
+    assert img.get(0, 0) == [127.0, 127.0, 127.0]

tests/dumps.py

@@ -0,0 +1,51 @@
+"""test of file dump functions """
+import os
+
+import floatimg
+
+TEST_PATH = os.path.join(os.path.dirname(__file__), "test.dump")
+
+# TODO refactor to fixture
+def create_dump():
+    width, height = 5, 5
+    img = floatimg.create_rgb(width, height)
+    # fill it to have something to compare
+    img.fill((64.0, 64.0, 64.0))
+    img.dump(TEST_PATH)
+
+
+def test_dump_to_file():
+    create_dump()
+
+    assert os.path.exists(TEST_PATH)
+    assert os.path.isfile(TEST_PATH)
+    assert os.path.getsize(TEST_PATH) == 320
+
+    os.remove(TEST_PATH)
+
+
+def test_infos():
+    create_dump()
+    floatimg.fileinfos(TEST_PATH) == 5, 5, floatimg.RGB
+    os.remove(TEST_PATH)
+
+
+def test_load():
+    create_dump()
+    width, height = 5, 5
+    img = floatimg.create_rgb(width, height)
+
+    img.load(TEST_PATH)
+    for y in range(height):
+        for x in range(width):
+            assert img.get(x, y) == [64.0, 64.0, 64.0]
+    os.remove(TEST_PATH)
+
+
+def test_create():
+    create_dump()
+    img = floatimg.create_from_dump(TEST_PATH)
+    for y in range(img.height):
+        for x in range(img.width):
+            assert img.get(x, y) == [64.0, 64.0, 64.0]
+    os.remove(TEST_PATH)