🖼️ OpenCV-Frame-Stacker

The OpenCV-Frame-Stacker is a Python snippet that allows you to stack multiple images or frames using the Numpy library. It provides a convenient way to arrange and combine images into a single canvas. 📸

✨ Features

• Stack grayscale images and colorful images: The stackFrames function supports stacking both grayscale and colorful images. You can mix grayscale images with images that have multiple channels.
• Stack multiple images or frames into a single canvas.
• Customizable stack shape and data type.

💻 Tested Platforms

• Linux (Tested ✔️)
• Windows (Tested ✔️)
• MacOS (Not Tested ❌)

🔗 Dependencies

To run this project, you need to have the following dependencies installed:

• 🐍 Python: Python is a programming language used by this project.
• 📦 pip: pip is the package installer for Python.
• 🖼️ OpenCV: OpenCV is a computer vision library used for image processing and manipulation.
• 🧮 Numpy: Numpy is a library for numerical computing in Python.

Please make sure to install these dependencies before running the project.

📥 Installation

1. Ensure you have Python installed (version 3.6 or higher).
2. Install the required dependencies:

Linux

pip3 install numpy opencv-python

Widnows

pip install numpy opencv-python

🛠️ Usage

⚠️ Consider the mutability of lists in Python before using this snippet. ⚠️

If you want to download the code and use it in your project, you have two options:

Option 1: Copy the code from main.py:

• Go to the repository where the code is located.
• Open the main.py file.
• Select all the code in the file and copy it.
• Paste the copied code into your own project file.

Option 2: Clone the repository:

• Open your terminal or command prompt.
• Navigate to the directory where you want to clone the repository.
• Run the following command to clone the repository:

git clone <repository-url>

Replace with the URL of the repository. Copy the code from main.py and use it in your project.

📃 Examples

Stacking Numpy Images

To stack numpy images or frames using the stackFrames function, make sure that all frames have an equal number of channels. This is important to ensure proper alignment and concatenation of the frames.

import cv2
import numpy as np


# Load the images or frames
image1 = cv2.imread("path/to/image1.png")
image2 = cv2.imread("path/to/image2.png")
image3 = cv2.imread("path/to/image3.png")

# Stack the frames
result = stackFrames(stack_shape=(2, 2), frames=[image1, image2, image3])

# Display or save the stacked image
cv2.imshow("Stacked Image", result)
cv2.waitKey(0)
cv2.destroyAllWindows()

📃 Examples

The general Stack (e.g., shape = (3,4) ) looks like:

---

Example 1: Stack shape = (3,1), Images = 3 (COLORFUL)

stackFrames(stack_shape=(3, 1), frames=[image_1, image_2, image_3])

---

Example 2: Stack shape = (3,2), Images = 6 (COLORFUL)

stackFrames(stack_shape=(3, 2), frames=[image_1, image_2, image_3, image_4, image_5, image_6])

---

Example 3: Stack shape = (5,2), Images = 4 (COLORFUL)

stackFrames(stack_shape=(5, 2), frames=[image_1, image_2, image_3, image_4])

---

Example 4: Stack shape = (2,3), Images = 3 (GRAYSCALE)

stackFrames(stack_shape=(2, 3), frames=[image_1, image_2, image_3])

---

Example 5: Stack shape = (3, 4), Images = 5 (Both GRAYSCALE and COLORFUL)

stackFrames(stack_shape=(3, 4), frames=[image_1, image_2, image_3, image_4, image_5])

---

Example 6: Stack shape = (2, 2), Images = 5 ERROR 🛑

stackFrames(stack_shape=(2, 2), frames=[image_1, image_2, image_3, image_4, image_5])

Outputs error 🛑:

    raise ValueError(
ValueError: 
The number of frames is too large for the current stack. Max number of frames for the stack (2, 2) is 4, got: 5

📃 Code Description

The stackFrames function is used to stack multiple images into a single composite image based on a specified stack shape. The function supports both grayscale and colorful images, allowing you to stack images with different channel dimensions.

Function Parameters

• stack_shape (tuple): A tuple specifying the desired shape of the image stack in terms of the number of rows and columns.
• frames (list | np.ndarray): A list of numpy arrays or a numpy array containing the input images to be stacked. Each element in the list or array represents an image.
• dtype: The data type of the output image. It determines the range and precision of pixel values. Defaults to np.uint8

Function Workflow

1. The function begins by checking if all elements in the frames list are of type np.ndarray. If any element is not a numpy array, a ValueError is raised.
2. Next, the function checks if all the images in the frames list are grayscale or colorful.
   • If all images are grayscale, a canvas is created with dimensions based on the specified stack shape.
   • If all images are colorful, a canvas with the same number of channels as the first image in the list is created.
   • If the images are a mix of grayscale and colorful, an equalization process is performed to ensure consistent channel dimensions.
3. The canvas is initialized as an array of zeros with the appropriate dimensions and data type.
4. The function then loops through the stack shape and places each image in the corresponding position on the canvas.
5. Finally, the function returns the composite image.

🙋 Contributing

🙌 Contributions to this project are welcome! If you have any ideas, improvements, or bug fixes, please submit a pull request 🛠️. For major changes, please open an issue to discuss your ideas beforehand 💡.

📜 License

This project is licensed under the MIT License 📜.

🙏 Acknowledgments

We would like to express our gratitude to the following projects for their contributions and inspiration:

• OpenCV: The OpenCV library for providing powerful computer vision and image processing capabilities that form the foundation of this project. 🌟

• NumPy: The NumPy library for providing efficient array manipulation and mathematical operations, which greatly enhances the functionality of the image stacking process. 🌟

• Prettier: Prettier, a code formatter that helps maintain consistent code style and readability. 🌟

Their dedication and efforts in developing these open-source projects have greatly benefited the development community.