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

README.md

@@ -2,7 +2,11 @@
 
 A pythonesque binding to FloatImg library available at https://git.tetalab.org/tTh/FloatImg
 
-python-FloatImg requires a quite recent Python 3 implementation (tested with 3.6.9).
+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
 
@@ -40,13 +44,15 @@ Or completely duplicate an existing image:
 new_img = img.clone()
 
 # with copying data
-new_img = img.clone(1)
+new_img = img.clone(True)
 ```
 
 ### Image manipulation
 
 #### Clear image
 
+Reset all pixels to zero.
+
 ```python
 img.clear()
 ```
@@ -60,13 +66,13 @@ img.copy_data(another_img)
 #### Set pixel value
 
 ```python
-img.put_rgb(x, y, (r, g, b))
+img.put(x, y, (r, g, b))
 ```
 
 #### Get pixel value
 
 ```python
-r, g, b = img.get_rgb(x, y)
+color = (r, g, b) = img.get(x, y)
 ```
 
 ### File manipulation
@@ -74,13 +80,13 @@ r, g, b = img.get_rgb(x, y)
 #### Dump image to file
 
 ```python
-img.dump_to_file("/tmp/image_dump")
+img.dump("/tmp/image_dump")
 ```
 
 #### Restore image data from a dump file
 
 ```python
-img.load_from_dump("/tmp/image_dump")
+img.load("/tmp/image_dump")
 ```
 
 #### Create a new image from a dump file
@@ -90,6 +96,8 @@ 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")
 ```

floatimg/image.py

@@ -126,22 +126,24 @@ class FloatImg:
     """
 
     # proxy attributes to the C_FloatImg structure
+    # TODO: now more about them
     magic = property(lambda self: self.c_img.magic)
-    width = property(lambda self: self.c_img.width)
-    height = property(lambda self: self.c_img.height)
-    type_id = property(lambda self: self.c_img.type)
     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(
+    # R = property(
-        lambda self: pointer(self.c_img.contents.R)[: self.width * self.height]
+    #     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)
 
     #######################################################################################################
@@ -160,11 +162,15 @@ class FloatImg:
     #######################################################################################################
     def clear(self):
         """clear data"""
-        return c_fimg_clear(self.c_img_p)
+        assert c_fimg_clear(self.c_img_p) == 0
 
     #######################################################################################################
-    def clone(self, flags=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)
@@ -180,18 +186,18 @@ class FloatImg:
         return c_fimg_str_type(self.c_img.type).decode("utf-8")
 
     #######################################################################################################
-    def rgb_constant(self, r, v, b):
+    def fill(self, color):
-        assert c_fimg_rgb_constant(self.c_img_p, r, v, b) == 0
+        assert c_fimg_rgb_constant(self.c_img_p, *color) == 0
 
     #######################################################################################################
-    def get_rgb(self, x, y):
+    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_rgb(self, x, y, rgb):
+    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)()
@@ -200,7 +206,7 @@ class FloatImg:
         assert c_fimg_put_rgb(self.c_img_p, x, y, ct.pointer(c_rgb)) == 0
 
     #######################################################################################################
-    def dump_to_file(self, fname):
+    def dump(self, fname):
         """save data to a dump file"""
         # TODO use system encoding instead of utf-8
         assert (
@@ -211,7 +217,7 @@ class FloatImg:
         )
 
     #######################################################################################################
-    def load_from_dump(self, fname):
+    def load(self, fname):
         """load data from a dump. size and type have to be compatible"""
         assert (
             c_fimg_load_from_dump(
@@ -220,6 +226,12 @@ class FloatImg:
             == 0
         )
 
+    # TODO
+    # fimg_plot_rgb
+    # fimg_add_rgb
+
+    # export(fname, flags) : depending file extension, save to the correct format
+
 
 ###########################################################################################################
 def fileinfos(fname):
@@ -252,7 +264,7 @@ 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_from_dump(fname)
+    img.load(fname)
     return img
 
 

tests/basics.py

@@ -21,26 +21,26 @@ def test_clone():
     width = 5
     height = 5
     img = floatimg.create(width, height, floatimg.RGB)
-    img.rgb_constant(127.0, 127.0, 127.0)
+    img.fill((127.0, 127.0, 127.0))
 
     # clone without copying pixel values
-    img2 = img.clone()
+    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_rgb(x, y) != img2.get_rgb(x, y)
+            assert img.get(x, y) != img2.get(x, y)
 
-    img2 = img.clone(1)
+    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_rgb(x, y) == img2.get_rgb(x, y)
+            assert img.get(x, y) == img2.get(x, y)
 
 
 def test_rgb_constant():
@@ -48,10 +48,11 @@ def test_rgb_constant():
     height = 5
     color = [127.0, 127.0, 127.0]
     img = floatimg.create_rgb(width, height)
-    img.rgb_constant(*color)
+    img.fill(color)
     for y in range(height):
         for x in range(width):
-            assert img.get_rgb(x, y) == color
+            assert img.get(x, y) == color
+
 
 
 def test_copy_data():
@@ -59,27 +60,27 @@ def test_copy_data():
     height = 5
     color = [127.0, 127.0, 127.0]
     img = floatimg.create_rgb(width, height)
-    img.rgb_constant(*color)
+    img.fill(color)
 
     img2 = floatimg.create_rgb(width, height)
-    img2.rgb_constant(64.0, 64.0, 64.0)
+    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_rgb(x, y) == img2.get_rgb(x, y)
+            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.rgb_constant(*color)
+    img.fill(color)
     img.clear()
     for y in range(height):
         for x in range(width):
-            assert img.get_rgb(x, y) == [0.0, 0.0, 0.0]
+            assert img.get(x, y) == [0.0, 0.0, 0.0]
 
 
 def test_str_type():
@@ -100,6 +101,6 @@ def test__str__():
 def test_put_rgb():
     width, height = 5, 5
     img = floatimg.create_rgb(width, height)
-    assert img.get_rgb(0, 0) == [0.0, 0.0, 0.0]
+    assert img.get(0, 0) == [0.0, 0.0, 0.0]
-    img.put_rgb(0, 0, [127.0, 127.0, 127.0])
+    img.put(0, 0, (127.0, 127.0, 127.0))
-    assert img.get_rgb(0, 0) == [127.0, 127.0, 127.0]
+    assert img.get(0, 0) == [127.0, 127.0, 127.0]

tests/dumps.py

@@ -10,8 +10,8 @@ def create_dump():
     width, height = 5, 5
     img = floatimg.create_rgb(width, height)
     # fill it to have something to compare
-    img.rgb_constant(64.0, 64.0, 64.0)
+    img.fill((64.0, 64.0, 64.0))
-    img.dump_to_file(TEST_PATH)
+    img.dump(TEST_PATH)
 
 
 def test_dump_to_file():
@@ -34,10 +34,11 @@ def test_load():
     create_dump()
     width, height = 5, 5
     img = floatimg.create_rgb(width, height)
-    img.load_from_dump(TEST_PATH)
+
+    img.load(TEST_PATH)
     for y in range(height):
         for x in range(width):
-            assert img.get_rgb(x, y) == [64.0, 64.0, 64.0]
+            assert img.get(x, y) == [64.0, 64.0, 64.0]
     os.remove(TEST_PATH)
 
 
@@ -46,5 +47,5 @@ def test_create():
     img = floatimg.create_from_dump(TEST_PATH)
     for y in range(img.height):
         for x in range(img.width):
-            assert img.get_rgb(x, y) == [64.0, 64.0, 64.0]
+            assert img.get(x, y) == [64.0, 64.0, 64.0]
     os.remove(TEST_PATH)