Add leak detection and leak fixes

CHANGELOG.md

@@ -0,0 +1,7 @@
+## v1.1.0
+
+
+
+## v1.0.0
+
+* Initial release of Video4j

README.md

@@ -8,9 +8,9 @@ Video4j is a highlevel library ontop of `org.openpnp:opencv` which provides APIs
 
 ```xml
 <dependency>
-	<groupId>io.metaloom.video</groupId>
-	<artifactId>video4j</artifactId>
-	<version>1.0.0</version>
+  <groupId>io.metaloom.video</groupId>
+  <artifactId>video4j</artifactId>
+  <version>1.0.0</version>
 </dependency>
 ```
 
@@ -53,7 +53,6 @@ try (Video video = Videos.open(BIG_BUCK_BUNNY2_PATH)) {
     // Display the frame in a window
     ImageUtils.show(image);
 }   
-
 ```
 
 ## Streaming of frames
@@ -125,6 +124,27 @@ The `VideoUtils` contains methods to startup a very basic video player which can
 
 The `CVUtils` contain utility methods that can be used to modify the frame image data (e.g blur, greyscale, canny filter, contrast..)
 
+## Tips / Pitfalls
+
+
+### Memory
+
+Video frame data will be provided via opencv `Mat` objects. These objects are linked to JNI data which means they need to be manually released after usage. The `MatProvider` methods can be used to instantiate new `Mat` objects. The provider will in-turn keep track of the instances. The `CVUtils#free` methods can be used to `release` the mat objects after use.
+For development the `MatProvider#printLeaks` method can be used to verify that all instances have been released.
+
+### Performance
+
+When using `Mat` instances it is advised to reuse them if possible and to provide existing Mats to read frame data. This can for example be done by usage of the  `Video#frame(Mat)` method.
+
+```java
+Mat frame = MatProvider.mat();
+while (true) {
+    if (!video.frame(frame)) {
+        break;
+    }
+…
+```
+
 ## Requirements / Limitations
 
 The library uses OpenCV via JNI. Thus the JNI library `libopencv4.5-jni` must be installed on the host system.

pom.xml

@@ -5,7 +5,7 @@
 
 	<groupId>io.metaloom.video</groupId>
 	<artifactId>video4j</artifactId>
-	<version>1.0.0</version>
+	<version>1.0.1-SNAPSHOT</version>
 
 	<parent>
 		<groupId>io.metaloom</groupId>

src/main/java/io/metaloom/video4j/Video.java

@@ -40,6 +40,14 @@ static Video open(String path) {
 	 */
 	Mat frameToMat();
 
+	/**
+	 * Read the next frame data into the provided {@link Mat}
+	 * 
+	 * @param mat
+	 * @return True if the frame could be read
+	 */
+	boolean frame(Mat mat);
+
 	/**
 	 * Read the current frame and return it as a resized buffered image. This operation will advance the position to the next frame.
 	 * 
@@ -68,6 +76,15 @@ static Video open(String path) {
 	 */
 	Mat boxedFrameToMat(int width);
 
+	/**
+	 * Read the next frame.
+	 * 
+	 * @param frame
+	 * @param width
+	 * @return True if the frame could be reads
+	 */
+	boolean boxedFrame(Mat frame, int width);
+
 	/**
 	 * Return the current set frame.
 	 * 

src/main/java/io/metaloom/video4j/VideoFrame.java

@@ -4,7 +4,7 @@
 
 import org.opencv.core.Mat;
 
-public interface VideoFrame {
+public interface VideoFrame extends AutoCloseable {
 
 	/**
 	 * Return the frame number.

src/main/java/io/metaloom/video4j/impl/MatProvider.java

@@ -0,0 +1,44 @@
+package io.metaloom.video4j.impl;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Map.Entry;
+
+import org.opencv.core.Mat;
+import org.opencv.core.Scalar;
+
+public class MatProvider {
+
+	public static Map<Mat, UnreleasedMatException> trackedInstances = new HashMap<>();
+
+	public static Mat mat() {
+		Mat mat = new Mat();
+		track(mat);
+		return mat;
+	}
+
+	public static void released(Mat mat) {
+		mat.release();
+		trackedInstances.remove(mat);
+	}
+
+	public static boolean hasLeaks() {
+		return !trackedInstances.isEmpty();
+	}
+
+	public static void printLeaks() {
+		for (Entry<Mat, UnreleasedMatException> entry : trackedInstances.entrySet()) {
+			entry.getValue().printStackTrace();
+		}
+	}
+
+	public static Mat empty(Mat source) {
+		Mat mat = new Mat(source.size(), source.type(), Scalar.all(0f));
+		track(mat);
+		return mat;
+	}
+
+	private static void track(Mat mat) {
+		trackedInstances.put(mat, new UnreleasedMatException());
+	}
+}