lint, use cv.Mat.table to improve performance, fix bit.cpp for lua 5.3, 5.4

Author: smbape

CMakeLists.txt

@@ -333,7 +333,7 @@ foreach(item ${files_to_change})
   vcpkg_regex_replace_string("${item}" "(/lua-opencv/releases/download/v|/lua-opencv/tree/v)[0-9]+\\.[0-9]+\\.[0-9]+" "\\1${PROJECT_VERSION}")
   vcpkg_regex_replace_string("${item}" "(opencv-|/opencv/opencv/blob/|opencv_lua )[0-9]+\\.[0-9]+\\.[0-9]+" "\\1${OpenCV_VERSION}")
   vcpkg_regex_replace_string("${item}" "(--branch )[0-9]+\\.[0-9]+\\.[0-9]+( https://github.com/opencv/opencv)" "\\1${OpenCV_VERSION}\\2")
-  vcpkg_regex_replace_string("${item}" "(--branch )[0-9]+\\.[0-9]+\\.[0-9]+( https://github.com/smbape/lua-opencv)" "\\1${PROJECT_VERSION}\\2")
+  vcpkg_regex_replace_string("${item}" "(--branch v)[0-9]+\\.[0-9]+\\.[0-9]+( https://github.com/smbape/lua-opencv)" "\\1${PROJECT_VERSION}\\2")
 
   # Force LF EOL
   configure_file(${item} ${item} @ONLY NEWLINE_STYLE LF)

README.md

@@ -33,6 +33,15 @@ Therefore the [OpenCV documentation](https://docs.opencv.org/4.x/index.html) sho
     - [Windows](#windows-2)
     - [Linux](#linux-2)
 - [Hosting you own binary rocks](#hosting-you-own-binary-rocks)
+- [Keyword arguments](#keyword-arguments)
+- [How to translate python/c++ code](#how-to-translate-pythonc-code)
+  - [Python translation example](#python-translation-example)
+- [Python Gotchas](#python-gotchas)
+  - [1-indexed](#1-indexed)
+  - [Instance method calls](#instance-method-calls)
+  - [Strict compliance with documentation](#strict-compliance-with-documentation)
+  - [Memory](#memory)
+  - [Matrix manipulation](#matrix-manipulation)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -206,21 +215,25 @@ Sources:
 --]]
 
 local img_rgb = cv.imread("mario.png")
-assert(img_rgb, "file could not be read, check with os.path.exists()")
+assert(not img_rgb:empty(), "file could not be read, check with os.path.exists()")
 local img_gray = cv.cvtColor(img_rgb, cv.COLOR_BGR2GRAY)
 local template = cv.imread("mario_coin.png", cv.IMREAD_GRAYSCALE)
-assert(template, "file could not be read, check with os.path.exists()")
+assert(not template:empty(), "file could not be read, check with os.path.exists()")
 
 local h, w = template.height, template.width
 
-local res = cv.matchTemplate(img_gray,template,cv.TM_CCOEFF_NORMED)
+local res = cv.matchTemplate(img_gray, template, cv.TM_CCOEFF_NORMED)
 local threshold = 0.8
 
-for j=1,res.rows do
+-- transform into an lua table for faster processing in lua
+local rows, cols = res.rows, res.cols
+res = res:table()
+
+for j = 1, rows do
     local y = j - 1
-    for i=1,res.cols do
+    for i = 1, cols do
         local x = i - 1
-        if res(y, x) >= threshold then
+        if res[j][i] >= threshold then
             cv.rectangle(img_rgb, { x, y }, { x + w, y + h }, { 0, 0, 255 }, 2)
         end
     end
@@ -304,3 +317,183 @@ For example, if you uploaded it into http://example.com/binary-rock/, you can in
 ```sh
 luarocks install --server=http://example.com/binary-rock opencv_lua
 ```
+
+## Keyword arguments
+
+Similar to python [keyword arguments](https://docs.python.org/3/glossary.html#term-argument) or c# [Named parameters](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/named-and-optional-arguments#named-arguments), keyword arguments free you from matching the order of arguments to the order of parameters in the parameter lists of called methods.
+
+When a function has multiple default parameters, keyword arguments allows you to override only the needed parameters without specifying the previous default parameters.
+
+As an example, given the documentation of [cv.normalize](https://docs.opencv.org/4.x/d2/de8/group__core__array.html#ga87eef7ee3970f86906d69a92cbf064bd)
+
+```cpp
+void cv::normalize  (   InputArray       src,
+                        InputOutputArray dst,
+                        double           alpha = 1,
+                        double           beta = 0,
+                        int              norm_type = NORM_L2,
+                        int              dtype = -1,
+                        InputArray       mask = noArray()
+    )       
+Python:
+    cv.normalize( src, dst[, alpha[, beta[, norm_type[, dtype[, mask]]]]] ) -> dst
+```
+
+the following expressions are equivalent:
+
+```lua
+cv.normalize(src, dst, alpha, beta, norm_type, dtype, mask)
+cv.normalize(src, dst, alpha, beta, norm_type, dtype, opencv_lua.kwargs({ mask = mask }))
+cv.normalize(src, dst, alpha, beta, norm_type, opencv_lua.kwargs({ dtype = dtype, mask = mask }))
+cv.normalize(src, dst, alpha, beta, opencv_lua.kwargs({ norm_type = norm_type, dtype = dtype, mask = mask }))
+cv.normalize(src, dst, alpha, opencv_lua.kwargs({ beta = beta, norm_type = norm_type, dtype = dtype, mask = mask }))
+cv.normalize(src, dst, opencv_lua.kwargs({ alpha = alpha, beta = beta, norm_type = norm_type, dtype = dtype, mask = mask }))
+cv.normalize(src, opencv_lua.kwargs({ dst = dst, alpha = alpha, beta = beta, norm_type = norm_type, dtype = dtype, mask = mask }))
+cv.normalize(opencv_lua.kwargs({ src = src, dst = dst, alpha = alpha, beta = beta, norm_type = norm_type, dtype = dtype, mask = mask }))
+```
+
+Of course, optional parameters are not mandatory. In other words, if you only want to change the `norm_type` parameter, you can do
+
+```lua
+cv.normalize(src, dst, opencv_lua.kwargs({ norm_type = cv.NORM_L1 }))
+```
+
+## How to translate python/c++ code
+
+The transformation will usually be straight from python.
+
+`tuples` and `arrays` becomes `tables`.
+
+`numpy` calls and `arrays` manipulations have their `cv.Mat` counter parts.
+
+`keyword arguments` will be wrapped within `opencv_lua.kwargs`.
+
+### Python translation example
+
+```python
+import cv2 as cv
+
+img = cv.imread(cv.samples.findFile("pic1.png"))
+img_grey = cv.cvtColor(img, cv.COLOR_BGR2GRAY)
+ret, thresh = cv.threshold(img_grey, 100, 255, cv.THRESH_BINARY)
+contours, hierarchy = cv.findContours(thresh, cv.RETR_TREE, cv.CHAIN_APPROX_SIMPLE)
+
+print(f"Found { len(contours) } contours")
+
+cv.drawContours(img, contours, -1, ( 0, 0, 255 ) , 2)
+
+cv.imshow("Image", img)
+cv.waitKey()
+cv.destroyAllWindows()
+```
+
+```lua
+local opencv_lua = require("opencv_lua")
+local cv = opencv_lua.cv
+
+local img = cv.imread(cv.samples.findFile("pic1.png"))
+local img_grey = cv.cvtColor(img, cv.COLOR_BGR2GRAY)
+local ret, thresh = cv.threshold(img_grey, 100, 255, cv.THRESH_BINARY)
+local contours, hierarchy = cv.findContours(thresh, cv.RETR_TREE, cv.CHAIN_APPROX_SIMPLE)
+
+print("Found " .. #contours .. " contours")
+
+cv.drawContours(img, contours, -1, { 0, 0, 255 }, 2)
+
+cv.imshow("Image", img)
+cv.waitKey()
+cv.destroyAllWindows()
+```
+
+## Python Gotchas
+
+### 1-indexed
+
+Arrays are 1-indexed in `lua`, and 0-indexed in python. Therefore, if you see in python `p[0]`, you should write in lua `p[1]`
+
+More over, opencv functions still expect 0-indexed parameters. For exemple
+
+```lua
+for i = 1, #contours do
+    -- Notice the i - 1
+    cv.drawContours(src, contours, i - 1, {0, 0, 255}, 2)
+end
+```
+
+### Instance method calls
+
+Instance method are called with ':' not '.'.
+
+If you see in python
+
+```python
+cap = cv.VideoCapture(camId)
+read, frame = cap.read()
+```
+
+You should write in lua
+
+```python
+cap = cv.VideoCapture(camId)
+read, frame = cap:read()
+```
+
+### Strict compliance with documentation
+
+For backwards compatibility, python still allow an old syntax for enums and call constructors. This library does not.
+
+If you see in python
+
+```python
+cv.ml.SVM_create(...)
+cv.ml.SVM_C_SVC
+cv.TERM_CRITERIA_MAX_ITER
+```
+
+You should write in lua
+
+```lua
+cv.ml.SVM.create(...)
+cv.ml.SVM.C_SVC
+cv.TermCriteria.MAX_ITER
+```
+
+### Memory
+
+Image processing can use up a lot of memory. Relying solely on the behaviour of the garbage collector can cause your program to consume more memory than necessary.
+
+Therefore, think about calling `collectgarbage` in those cases.
+
+```lua
+local cap = cv.VideoCapture(0)
+while true do
+    -- Without this, memory grows indefinitely
+    collectgarbage()
+
+    local read, frame = cap:read()
+    cv.imshow("capture camera", frame)
+    if cv.waitKey(0) == 0x1b then break end
+end
+```
+
+### Matrix manipulation
+
+For maximum speed performance, when you need to manipulate matrices in lua, convert them `table`, do your manipulation and convert them back to matrices
+
+```lua
+-- transform into an lua table for faster processing in lua
+local rows, cols, type = res.rows, res.cols, res:type()
+res = res:table()
+
+for j = 1, rows do
+    local y = j - 1
+    for i = 1, cols do
+        local x = i - 1
+        if res[j][i] >= threshold then
+            cv.rectangle(img_rgb, { x, y }, { x + w, y + h }, { 0, 0, 255 }, 2)
+        end
+    end
+end
+
+res = cv.Mat.createFromArray(res, type)
+```

docs/docs.md

@@ -2491,6 +2491,7 @@
   - [cv.Mat.step1](#cvmatstep1)
   - [cv.Mat.sum](#cvmatsum)
   - [cv.Mat.t](#cvmatt)
+  - [cv.Mat.table](#cvmattable)
   - [cv.Mat.tolist](#cvmattolist)
   - [cv.Mat.total](#cvmattotal)
   - [cv.Mat.type](#cvmattype)
@@ -28857,9 +28858,9 @@ lua:
 
 ```cpp
 static cv::Mat cv::Mat::createFromArray( sol::table array,
-                                         int        depth = -1 );
+                                         int        type = CV_64F );
 lua:
-    cv.Mat.createFromArray( array[, depth] ) -> retval
+    cv.Mat.createFromArray( array[, type] ) -> retval
 ```
 
 ### cv.Mat.createFromVec2b
@@ -30047,12 +30048,20 @@ lua:
     oMat:t() -> retval
 ```
 
+### cv.Mat.table
+
+```cpp
+sol::table cv::Mat::table();
+lua:
+    oMat:table() -> retval
+```
+
 ### cv.Mat.tolist
 
 ```cpp
-sol::table cv::Mat::tolist();
+sol::table cv::Mat::table();
 lua:
-    oMat:tolist() -> retval
+    oMat:table() -> retval
 ```
 
 ### cv.Mat.total

generator/declarations/Mat.js

@@ -496,10 +496,11 @@ module.exports = ({ self, self_get, shared_ptr }) => {
 
         ["cv.Mat.createFromArray", "Mat", ["/S", "/Call=::cvextra::createMatFromArray", "/Expr=$0, lua"], [
             ["sol::table", "array", "", []],
-            ["int", "depth", "-1", []],
+            ["int", "type", "CV_64F", []],
         ], "", ""],
 
         ["cv.Mat.tolist", "sol::table", ["/Call=::cvextra::tolistMat", `/Expr=${ self }, lua`], [], "", ""],
+        ["cv.Mat.table", "sol::table", ["/Call=::cvextra::tolistMat", `/Expr=${ self }, lua`], [], "", ""],
     ];
 
     const types = new Set(["int", "float", "double"]);

samples/01-show-image.lua

@@ -1,4 +1,4 @@
-package.path = arg[0]:gsub("[^/\\]+%.lua", '?.lua;'):gsub('/', package.config:sub(1,1)) .. package.path
+package.path = arg[0]:gsub("[^/\\]+%.lua", '?.lua;'):gsub('/', package.config:sub(1, 1)) .. package.path
 
 local opencv_lua = require("init")
 local cv = opencv_lua.cv

samples/02-video-capture-camera.lua

@@ -1,4 +1,4 @@
-package.path = arg[0]:gsub("[^/\\]+%.lua", '?.lua;'):gsub('/', package.config:sub(1,1)) .. package.path
+package.path = arg[0]:gsub("[^/\\]+%.lua", '?.lua;'):gsub('/', package.config:sub(1, 1)) .. package.path
 
 local opencv_lua = require("init")
 local cv = opencv_lua.cv
@@ -29,7 +29,7 @@ while true do
     -- Flip the image horizontally to give the mirror impression
     local frame = cv.flip(frame, 1)
 
-    cv.putText(frame, string.format("FPS : %.2f", fps), { 10, 30 }, cv.FONT_HERSHEY_PLAIN, 2, {255, 0, 255}, 3)
+    cv.putText(frame, string.format("FPS : %.2f", fps), { 10, 30 }, cv.FONT_HERSHEY_PLAIN, 2, { 255, 0, 255 }, 3)
     cv.imshow("capture camera", frame)
 
     local key = cv.waitKey(CAP_SPF)

samples/03-video-capture-file.lua

@@ -1,4 +1,4 @@
-package.path = arg[0]:gsub("[^/\\]+%.lua", '?.lua;'):gsub('/', package.config:sub(1,1)) .. package.path
+package.path = arg[0]:gsub("[^/\\]+%.lua", '?.lua;'):gsub('/', package.config:sub(1, 1)) .. package.path
 
 local opencv_lua = require("init")
 local cv = opencv_lua.cv

samples/04-rotate-image.lua

@@ -1,4 +1,4 @@
-package.path = arg[0]:gsub("[^/\\]+%.lua", '?.lua;'):gsub('/', package.config:sub(1,1)) .. package.path
+package.path = arg[0]:gsub("[^/\\]+%.lua", '?.lua;'):gsub('/', package.config:sub(1, 1)) .. package.path
 
 local opencv_lua = require("init")
 local cv = opencv_lua.cv

samples/05-drawing-contours.lua

@@ -1,4 +1,4 @@
-package.path = arg[0]:gsub("[^/\\]+%.lua", '?.lua;'):gsub('/', package.config:sub(1,1)) .. package.path
+package.path = arg[0]:gsub("[^/\\]+%.lua", '?.lua;'):gsub('/', package.config:sub(1, 1)) .. package.path
 
 local opencv_lua = require("init")
 local cv = opencv_lua.cv

samples/06-template-matching.lua

@@ -1,4 +1,4 @@
-package.path = arg[0]:gsub("[^/\\]+%.lua", '?.lua;'):gsub('/', package.config:sub(1,1)) .. package.path
+package.path = arg[0]:gsub("[^/\\]+%.lua", '?.lua;'):gsub('/', package.config:sub(1, 1)) .. package.path
 
 local opencv_lua = require("init")
 local cv = opencv_lua.cv
@@ -9,21 +9,25 @@ Sources:
 --]]
 
 local img_rgb = cv.imread(cv.samples.findFile("mario.png"))
-assert(img_rgb, "file could not be read, check with os.path.exists()")
+assert(not img_rgb:empty(), "file could not be read, check with os.path.exists()")
 local img_gray = cv.cvtColor(img_rgb, cv.COLOR_BGR2GRAY)
 local template = cv.imread(cv.samples.findFile("mario_coin.png"), cv.IMREAD_GRAYSCALE)
-assert(template, "file could not be read, check with os.path.exists()")
+assert(not template:empty(), "file could not be read, check with os.path.exists()")
 
 local h, w = template.height, template.width
 
-local res = cv.matchTemplate(img_gray,template,cv.TM_CCOEFF_NORMED)
+local res = cv.matchTemplate(img_gray, template, cv.TM_CCOEFF_NORMED)
 local threshold = 0.8
 
-for j=1,res.rows do
+-- transform into an lua table for faster processing in lua
+local rows, cols = res.rows, res.cols
+res = res:table()
+
+for j = 1, rows do
     local y = j - 1
-    for i=1,res.cols do
+    for i = 1, cols do
         local x = i - 1
-        if res(y, x) >= threshold then
+        if res[j][i] >= threshold then
             cv.rectangle(img_rgb, { x, y }, { x + w, y + h }, { 0, 0, 255 }, 2)
         end
     end