Before any image processing can occur, we must first understand how OpenCV stores and manipulates image data. The fundamental data structure for this purpose is the Mat class. This module will cover the properties of this essential class and then demonstrate the core operations of reading image files from disk, writing them back, and displaying them in a graphical user interface.

A Note on File Paths: Throughout the following code examples, you will see file paths represented as “path/to/your/image.jpg”. This is a placeholder. To run these examples, you must replace this string with the actual, valid path to an image file on your system.

3.1 Digital Image Representation: The Mat Class

The Mat class, found in the org.opencv.core package, is an n-dimensional array designed to store not only 2D image data but also other numerical information like voxel volumes, point clouds, and histograms.

Conceptually, a Mat object consists of two distinct parts:

• The header: This is a small, constant-size part that contains metadata about the matrix, such as its size (rows and columns), the data type of its elements, and the memory address where the data is stored.
• The pointer: This points to the actual matrix of pixel data. The size of this data block can vary greatly depending on the image dimensions.

This two-part structure is a key feature, as it allows multiple Mat objects to point to the same data block, making operations like creating a region of interest (ROI) highly efficient.

Mat Class Constructors

The Mat class provides several constructors for creating matrices. The table below outlines some of the most common ones.

Note: The type parameter uses constants from the CvType class, such as CV_8UC1 for an 8-bit single-channel image (grayscale) or CV_8UC3 for an 8-bit three-channel image (color).

Key Mat Class Methods

The Mat class also includes a rich set of methods for accessing and manipulating its data.

Practical Example: Creating and Displaying a Matrix

Let’s see a practical example of creating a matrix. The process involves three main steps:

1. Load the native library: Every OpenCV Java program must start by loading the native library.
2. Instantiate the Mat class: Use a constructor to create a new matrix.
3. Fill the matrix: Use methods like row() and setTo() to populate the matrix with data.

import org.opencv.core.Core;

import org.opencv.core.CvType;

import org.opencv.core.Mat;

import org.opencv.core.Scalar;

public class DisplayingMatrix {

public static void main(String[] args) {

//Loading the core library

System.loadLibrary(Core.NATIVE_LIBRARY_NAME);

//Creating a matrix

Mat matrix = new Mat(5, 5, CvType.CV_8UC1, new Scalar(0));

//Retrieving the row with index 0

Mat row0 = matrix.row(0);

//setting values of all elements in the row with index 0

row0.setTo(new Scalar(1));

//Retrieving the column with index 3

Mat col3 = matrix.col(3);

//setting values of all elements in the column with index 3

col3.setTo(new Scalar(3));

//Printing the matrix

System.out.println(“OpenCV Mat data:\n” + matrix.dump());

}

}

Program Output:

OpenCV Mat data:

[ 1, 1, 1, 3, 1;

0, 0, 0, 3, 0;

0, 0, 0, 3, 0;

0, 0, 0, 3, 0;

0, 0, 0, 3, 0]

3.2 Fundamental Image Input/Output Operations

The Imgcodecs class, located in the org.opencv.imgcodecs package, provides the core methods for reading images from files and writing them back to disk.

Reading an Image

The primary method for reading an image is imread(filename). It accepts a string representing the path to the image file and returns a Mat object containing the image data.

The process involves three steps:

1. Load the OpenCV native library.
2. Instantiate the Imgcodecs class.
3. Call the imread() method with the file path.

import org.opencv.core.Core;

import org.opencv.core.Mat;

import org.opencv.imgcodecs.Imgcodecs;

public class ReadingImages {

public static void main(String args[]) {

//Loading the OpenCV core library

System.loadLibrary( Core.NATIVE_LIBRARY_NAME );

//Reading the Image from the file

String file = “path/to/your/image.jpg”;

Mat matrix = Imgcodecs.imread(file);

System.out.println(“Image Loaded: ” + (matrix.empty() ? “failure” : “success”));

}

}

Writing an Image

To save a Mat object to an image file, we use the imwrite(filename, mat) method. It takes two parameters:

• filename: A string representing the path and filename where the image should be saved. The file extension (e.g., .jpg, .png) determines the format.
• mat: The Mat object containing the image data to be written.

import org.opencv.core.Core;

import org.opencv.core.Mat;

import org.opencv.imgcodecs.Imgcodecs;

public class WritingImages {

public static void main(String args[]) {

//Loading the OpenCV core library

System.loadLibrary(Core.NATIVE_LIBRARY_NAME);

//Reading the Image from the file and storing it in to a Matrix object

String inputFile = “path/to/your/image.jpg”;

Mat matrix = Imgcodecs.imread(inputFile);

System.out.println(“Image Loaded.”);

String outputFile = “path/to/your/image_resaved.jpg”;

//Writing the image

Imgcodecs.imwrite(outputFile, matrix);

System.out.println(“Image Saved.”);

}

}

Executing this code will read the input image and save a new copy to the specified output path.

3.3 Displaying Images in a Graphical User Interface (GUI)

Simply reading and writing images is not enough; we often need to display them. Since OpenCV’s Mat object is not directly compatible with Java’s native GUI libraries (like AWT/Swings or JavaFX), a conversion process is required.

Converting Mat to BufferedImage

To display a Mat object in a Java GUI, we must first convert it to a java.awt.image.BufferedImage. This is a multi-step process:

1. Encode the Mat to MatOfByte: Use the Imgcodecs.imencode() method to convert the raw pixel data in the Mat object into a memory buffer formatted as a standard image type (e.g., .jpg). This places the result in a MatOfByte object.
2. Convert MatOfByte to a byte array: Use the toArray() method on the MatOfByte object to get a standard Java byte[].
3. Create an InputStream: Create a java.io.ByteArrayInputStream from the byte array.
4. Read the InputStream: Use the static method javax.imageio.ImageIO.read() to read the input stream and produce the final BufferedImage object.

Displaying with AWT/Swings

Once you have a BufferedImage, displaying it with Swings is straightforward. You create a JFrame, wrap the BufferedImage in an ImageIcon and then a JLabel, and add the label to the frame’s content pane.

import java.awt.image.BufferedImage;

import java.io.ByteArrayInputStream;

import java.io.InputStream;

import javax.imageio.ImageIO;

import javax.swing.ImageIcon;

import javax.swing.JFrame;

import javax.swing.JLabel;

import org.opencv.core.Core;

import org.opencv.core.Mat;

import org.opencv.core.MatOfByte;

import org.opencv.imgcodecs.Imgcodecs;

public class DisplayingImagesUsingSwings {

public static void main(String args[]) throws Exception {

//Loading the OpenCV core library

System.loadLibrary( Core.NATIVE_LIBRARY_NAME );

String file = “path/to/your/image.jpg”;

Mat image = Imgcodecs.imread(file);

//Encoding the image

MatOfByte matOfByte = new MatOfByte();

Imgcodecs.imencode(“.jpg”, image, matOfByte);

byte[] byteArray = matOfByte.toArray();

//Preparing the Buffered Image

InputStream in = new ByteArrayInputStream(byteArray);

BufferedImage bufImage = ImageIO.read(in);

//Instantiate JFrame

JFrame frame = new JFrame();

frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);

frame.getContentPane().add(new JLabel(new ImageIcon(bufImage)));

frame.pack();

frame.setVisible(true);

System.out.println(“Image Loaded”);

}

}

When run, this program will open a new GUI window displaying the loaded image.

Displaying with JavaFX

The process for JavaFX is similar, with an extra conversion step. After obtaining the BufferedImage, you convert it into a JavaFX WritableImage using the SwingFXUtils.toFXImage() method. This WritableImage can then be used to create an ImageView, which is the JavaFX component for displaying images.

import java.awt.image.BufferedImage;

import java.io.ByteArrayInputStream;

import java.io.IOException;

import java.io.InputStream;

import javafx.application.Application;

import javafx.embed.swing.SwingFXUtils;

import javafx.scene.Group;

import javafx.scene.Scene;

import javafx.scene.image.ImageView;

import javafx.scene.image.WritableImage;

import javafx.stage.Stage;

import javax.imageio.ImageIO;

import org.opencv.core.Core;

import org.opencv.core.Mat;

import org.opencv.core.MatOfByte;

import org.opencv.imgcodecs.Imgcodecs;

public class DisplayingImagesJavaFX extends Application {

@Override

public void start(Stage stage) throws IOException {

WritableImage writableImage = loadImage();

ImageView imageView = new ImageView(writableImage);

imageView.setFitHeight(400);

imageView.setFitWidth(600);

imageView.setPreserveRatio(true);

Group root = new Group(imageView);

Scene scene = new Scene(root, 600, 400);

stage.setTitle(“Displaying Image with JavaFX”);

stage.setScene(scene);

stage.show();

}

public WritableImage loadImage() throws IOException {

System.loadLibrary(Core.NATIVE_LIBRARY_NAME);

String file = “path/to/your/image.jpg”;

Mat image = Imgcodecs.imread(file);

MatOfByte matOfByte = new MatOfByte();

Imgcodecs.imencode(“.jpg”, image, matOfByte);

byte[] byteArray = matOfByte.toArray();

InputStream in = new ByteArrayInputStream(byteArray);

BufferedImage bufImage = ImageIO.read(in);

System.out.println(“Image Loaded”);

return SwingFXUtils.toFXImage(bufImage, null);

}

public static void main(String args[]) {

launch(args);

}

}

This JavaFX application will also create a window to display the specified image.

Having mastered the fundamentals of image representation and I/O, we are now ready to explore more advanced image manipulation techniques, such as converting between different color spaces.