Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/piero24/detect-decode-the-barcode

A two-stage pipeline for detecting and decoding barcodes from images.
https://github.com/piero24/detect-decode-the-barcode

barcode barcode-scanner huggingface object-detection opencv qrcode qrcode-scanner ultralytics yolov8

Last synced: about 1 month ago
JSON representation

A two-stage pipeline for detecting and decoding barcodes from images.

Awesome Lists containing this project

README 

          











  





    Barcode Detection & Decoding Pipeline





    

    

    

    

    

    

    

    

    

    

    

    

    

    

    

    





    A two-stage computer vision pipeline to detect and normalize barcodes from images using a fine-tuned YOLOv8 model.

    


    View a Demo »

    


    


    Report Bug

    •

    Request Feature




---







📔  Introduction




    This project documents the design and implementation of a two-stage pipeline for accurately detecting and decoding barcodes from images. The objective is to build a robust system capable of handling barcodes in real-world conditions, including variable lighting, perspective distortion, and image noise. The pipeline uses a fine-tuned YOLOv8s model for detection and a series of robust OpenCV functions for perspective correction.







> [!WARNING]

> This project is **incomplete**. While the barcode detection and perspective normalization stages are functional and robust, the final decoding stage was unsuccessful. The primary challenges were:

> - **Sensitivity to Noise:** Minor image noise and compression artifacts consistently corrupted the measured bar/space widths.

> - **Symbology Complexity:** Implementing a full, robust decoder for standards like Code 128 proved to be a significant challenge.

> - **Error Propagation:** Small errors in the initial module width calculation cascaded, rendering the entire decoding process unreliable.

>

> The code for the attempted decoding process is included to document the progress and showcase the techniques that were explored.







  

    

    

    

  

  

    

    

    

  

  

    

    

    

  

  

    

    

    

  








    The pipeline is designed to first locate barcodes in an image and then transform them into a clean, frontal view, which is the necessary prerequisite for any successful decoding attempt.






    PIPELINE OVERVIEW: The program takes an RGB image as input and processes it through a two-stage pipeline to prepare barcodes for decoding.

    
    

            
  1. 

                Barcode Detection with YOLOv8s

                
    

                    A YOLOv8s model, fine-tuned on a custom dataset of 5,000 images, is used to accurately detect the location of barcodes and produce precise bounding boxes.

                
    

            
    2. 

            
  2. 

                Perspective Correction & Normalization

                
    

                    For each detected barcode, a series of computer vision techniques (including blurring, thresholding, and contour analysis) is applied to isolate the barcode region. A perspective transformation is then used to un-warp the barcode into a flat, frontal, and horizontally-aligned image.

                
    

            
    3. 

            
  3. 

                Attempted Decoding (Incomplete)

                
    

                    The final step was to decode the normalized barcode image. This involved analyzing the pattern of black and white bars to extract the encoded information. Despite significant effort, this stage did not produce consistently reliable results. The code is provided for reference and as a starting point for future work.

                
    

            
    4. 

        





    

    
Example of the pipeline's output, showing the original image, cropped ROI, and the normalized/polished barcode ready for decoding.












    Try a demo on Google Colab





    

        

    




⇧






🛠  Built With




    This project is written in Python and relies on powerful libraries for deep learning and computer vision.





    Python • PyTorch • Ultralytics YOLOv8 • OpenCV • Hugging Face Hub



⇧







⚠️  Improvements & Future Work





    Given the incomplete nature of the project, the primary area for improvement is the decoding stage. Key steps to complete the pipeline include:



    

        
  • 

            Improve Image Preprocessing: Enhance the image cleaning steps after normalization to create a more uniform representation of the bars, reducing the impact of lighting inconsistencies and noise.

        
    • 

        
  • 

            Robust Module Width Calculation: Develop a more resilient method for calculating the fundamental module width (the width of the narrowest bar/space), as this is the most critical step for accurate decoding.

        
    • 

        
  • 

            Implement a Full Decoder: Build a complete decoding engine for a specific symbology (e.g., Code 128), including handling character sets, checksum validation, and special characters.

        
    • 

         
  • 

            Leverage Third-Party Decoding Libraries: As an alternative to a from-scratch implementation, integrate a proven, open-source decoding library like ZBar or ZXing to complete the pipeline quickly and reliably.

        
    • 




⇧







📚  Documentation





    The entire project is contained within a single Jupyter Notebook (`.ipynb`). The notebook is structured with markdown cells that explain each step of the process, from dependency installation to the final (attempted) decoding.




> [!TIP]

> The YOLOv8s model used for detection is downloaded automatically from the Piero2411/YOLOV8s-Barcode-Detection repository on Hugging Face Hub. No manual download is required.





    Key functionalities documented in the notebook include:

    
    

            
  • 

    Barcode Detection: Using a pre-trained YOLOv8s model.
    • 

            
  • 

    Image Normalization: A multi-pass approach to isolate and un-warp the barcode from its background.
    • 

            
  • 

    Perspective Transformation: Correcting for angled or distorted views to create a "bird's-eye view" of the barcode.
    • 

            
  • 

    Image Enhancement: Using Sobel gradients and morphological operations to create a clean, high-contrast barcode image.
    • 

            
  • 

    Decoding Logic: An implementation that attempts to read bar widths, calculate a module width, and map patterns to Code 128 characters.
    • 

        





    For a complete, in-depth view of the implementation and the challenges faced, please refer directly to the Jupyter Notebook.




> [!NOTE]

> The notebook includes plotting functions that visualize each step of the pipeline, from the original image and bounding box to the final normalized and polished barcode image. This is useful for debugging and understanding the impact of each computer vision technique.



⇧






🧰  Prerequisites




    To run this project, you will need a Python environment. A CUDA-enabled GPU is recommended for faster YOLOv8 inference, but the code will run on a CPU.




To install all necessary dependencies, run the following command in your terminal:



```sh

pip install ultralytics opencv-python matplotlib numpy huggingface_hub

```



⇧






⚙️  How to Start




    The project is provided as a Jupyter Notebook, which allows for easy, step-by-step execution and visualization of the results.







1. Clone the repo

  

```sh

git clone https://github.com/Piero24/Detect-Decode-the-Barcode.git

```

2. Navigate to the project directory

```sh

cd Detect-Decode-the-Barcode

```

3. Install the dependencies as described in the Prerequisites section.

4. Create an `input_images` folder in the root directory and place your images inside it.

5. Open the `Barcode_Detection_and_Decoding.ipynb` notebook in a compatible environment (like Jupyter Lab or Google Colab).

6. **Run the Notebook**: Execute the cells sequentially from top to bottom. The first run will automatically download the fine-tuned YOLOv8 model weights from Hugging Face Hub.



> [!NOTE] 

> The notebook is self-contained and includes detailed explanations for each code block. You can observe the output of the detection and normalization stages, as well as the logged failures of the decoding attempts.



⇧



---






📮  Responsible Disclosure




    We assume no responsibility for an improper use of this code and everything related to it. We do not assume any responsibility for damage caused to people and / or objects in the use of the code.





    By using this code even in a small part, the developers are declined from any responsibility.











    It is possible to have more information by viewing the following links: 

    Code of conduct

     • 

    License




⇧






🐛  Bug and Feature




    To report a bug or to request the implementation of new features, it is strongly recommended to use the ISSUES tool from Github »








    Here you may already find the answer to the problem you have encountered, in case it has already happened to other people. Otherwise you can report the bugs found.








    ATTENTION: To speed up the resolution of problems, it is recommended to answer all the questions present in the request phase in an exhaustive manner.











    (Even in the phase of requests for the implementation of new functions, we ask you to better specify the reasons for the request and what final result you want to obtain).







⇧


  

 --- 






🔍  License


MIT LICENSE







Permission is hereby granted, free of charge, to any person obtaining a copy

of this software and associated documentation files (the "Software"), to deal

in the Software without restriction, including...









    License Documentation »






⇧






📌  Third Party Licenses



In the event that the software uses third-party components for its operation, 




the individual licenses are indicated in the following section.







Software list:





  

    Software

    License owner 

    License type 

    Link

  

  

    YOLOv8

    Ultralytics

    AGPL-3.0

    here

  

  

    PyTorch

    PyTorch

    BSD-style

    here

  

  

    OpenCV

    OpenCV

    Apache-2.0 license

    here

  

  

    Hugging Face Hub

    Hugging Face

    Apache-2.0 license

    here

  



⇧



---

> *
 Copyrright (C) by Pietrobon Andrea 
 Released date: 15-09-2024*