Skip to content

User_Guide.md

Latest commit

 

History

History
394 lines (273 loc) · 13.6 KB

User_Guide.md

File metadata and controls

394 lines (273 loc) · 13.6 KB

PCB Defect Detection & Classification System

User Guide — Installation, Training & Application Usage

1. Overview

This guide walks you through every step required to get the PCB Defect Detection system running — from installing Python dependencies and training the classification model, to uploading images and exporting annotated results through the web interface.

No programming experience is required to operate the web application. Training the model does require downloading the DeepPCB dataset and running a batch script.

2. System Requirements

Requirement Minimum Recommended
Operating System Windows 10 Windows 11
Python 3.12 3.12
RAM 8 GB 16 GB
Disk space 5 GB (dataset + venv) 10 GB
CPU Any modern dual-core 8-core, 3 GHz+
GPU Not required NVIDIA (for faster training)
Browser Chrome / Edge Chrome

Python must be added to the system PATH during installation. When the Python installer runs, check the box labelled "Add Python to PATH" before clicking Install.

3. Installation

Step 1 — Obtain the Project

Option A: Clone from GitHub

git clone https://github.com/Cheekurthi-Vamsi/PCB-Defect-Detection-and-Classification-System.git
cd PCB-Defect-Detection-and-Classification-System

Option B: Download ZIP

  1. Visit the GitHub repository page.
  2. Click Code → Download ZIP.
  3. Extract to a folder of your choice (e.g. C:\Users\<you>\Desktop\PCB).

Step 2 — Create a Virtual Environment

Open a command prompt inside the project folder and run:

py -3.12 -m venv venv

This creates an isolated venv\ directory containing a clean Python 3.12 environment.

Step 3 — Install Dependencies

venv\Scripts\pip install -r requirements.txt

Packages installed:

Package Purpose
tensorflow-cpu Neural network inference and training
opencv-python Image processing (alignment, thresholding, contours)
streamlit Web application framework
Pillow PIL image loading and export
numpy Array operations
pandas DataFrame operations
matplotlib / seaborn Training plots and confusion matrix
scikit-learn Classification metrics
imutils Contour utilities

Installation typically takes 5–10 minutes depending on internet speed.

4. Preparing the Dataset

The system was trained and evaluated on the DeepPCB dataset, a publicly available collection of PCB image pairs annotated with six defect classes.

Step 1 — Download the Dataset

Download the DeepPCB dataset from:

https://github.com/Charmve/Surface-Defect-Detection/tree/master/DeepPCB

Step 2 — Place the Dataset

Extract the dataset into:

Image Subtraction\DeepPCB_dataset\

The expected folder structure is:

DeepPCB_dataset/
├── Missing_hole/
│   ├── 00041000_temp.jpg     ← template (defect-free reference)
│   ├── 00041000_test.jpg     ← test (potentially defective)
│   ├── 00041001_temp.jpg
│   └── ...
├── Mouse_bite/
├── Open_circuit/
├── Short/
├── Spur/
└── Spurious_copper/

Important: The six folder names must exactly match the class names listed above (case-sensitive).

5. Training the Model

The full training pipeline is automated in a single batch script that runs three consecutive processing stages.

Option A — One-Click Launch

Double-click run_pipeline.bat in the project root folder.

Option B — Manual Execution

# Stage 1: Image alignment, subtraction & mask generation
venv\Scripts\python "Image Subtraction\image_subraction.py"

# Stage 2: Contour detection, ROI extraction & dataset splitting
venv\Scripts\python "Contour Detection and ROI Extraction\roi_ext.py"

# Stage 3: EfficientNetB0 training
venv\Scripts\python "Model Training and Evaluation\Train.py"

What Each Stage Does

Stage 1 — Image Processing & Mask Generation
Reads every template/test image pair, aligns the test image to the template using ORB feature matching and homography, computes the absolute pixel difference, applies Otsu's thresholding to produce a binary defect mask, and saves aligned images, difference maps, and highlighted overlays. Typically completes in 2–10 minutes.

Stage 2 — ROI Extraction & Dataset Split
Reads the binary defect masks produced in Stage 1, detects defect contours, crops 128×128 ROI patches around each defect centroid, and splits them into training, validation, and test sets (70 / 15 / 15%, seed=42). Outputs are saved as labeled image files in a hierarchical folder structure ready for Keras ImageDataGenerator. Typically completes in 1–5 minutes.

Stage 3 — EfficientNetB0 Training
Loads the ROI patches and trains the EfficientNetB0 classifier in two phases: a warm-up phase with the backbone frozen, followed by a fine-tuning phase where the top 30 backbone layers are unfrozen at a lower learning rate. Training curves (accuracy + loss), confusion matrix, and a full classification report are saved to module3_output\. Training typically takes 30 to 90 minutes on CPU, or 5–15 minutes with a compatible GPU.

Training Outputs

All outputs are saved to Model Training and Evaluation\module3_output\:

File Description
best_model.keras Best model checkpoint (highest validation accuracy)
efficientnet_pcb_defect.keras Final epoch model
training_log.csv Accuracy and loss for each training epoch
training_curves.png Accuracy and loss over time plots
confusion_matrix.png 6×6 classification heatmap
evaluation_report.txt Full per-class precision, recall, F1, and accuracy summary

6. Evaluating on Unseen Test Images (Optional)

To measure real-world prediction performance on image pairs not used during training:

  1. Create the directory Model Training and Evaluation\test_images\
  2. Add paired images following this naming convention: 
    <id>_temp.jpg    ← reference image
<id>_test.jpg    ← defective image
  3. (Optional) Edit test_ground_truth.json to add known defect locations.
  4. Run the evaluation script: 
    venv\Scripts\python "Model Training and Evaluation\Single_Test.py"

Outputs are saved to module4_output\ and include annotated images, scatter plots of detected defects, a confusion matrix, and a final evaluation report with accuracy, F1, false-positive rate, and false-negative rate.

7. Using the Web Application

Step 1 — Launch the App

Option A: Double-click run_app.bat
Option B: Run in a terminal:

venv\Scripts\streamlit run app.py

The terminal will display:

  You can now view your Streamlit app in your browser.
  Local URL: http://localhost:8501

The browser opens automatically. If it does not, navigate to http://localhost:8501 manually.

Step 2 — Configure the Model Path (if needed)

The sidebar on the left shows the Model Path field. By default it points to:

Model Training and Evaluation\module3_output\best_model.keras

If you saved the model elsewhere, update this field before running inference.

Step 3 — Upload a PCB Image

Click the "Upload PCB Image" drag-and-drop zone, or drag a file onto it directly.

Supported formats: JPG, JPEG, PNG, BMP, TIF
Recommended: Clear, top-down, high-resolution PCB photograph

A preview of the uploaded image appears below the uploader immediately after selection.

Step 4 — Run Defect Detection

Click the blue "🚀 Run Defect Detection" button.

A loading spinner appears while the pipeline executes. Processing typically completes in under 3 seconds on a modern CPU.

Step 5 — Interpret the Results

Metric Tiles

Four summary tiles appear at the top of the results area:

Tile What It Shows
Defects Found Total number of defect regions detected in the image
Defect Types Number of distinct defect classes present
Avg Confidence Mean probability score across all detections (%)
Inference Time Total pipeline execution time (milliseconds)

Performance Status

A colored status banner shows whether the run met the ≤ 3 000 ms performance target:

  • ✅ Green — Inference completed within the target
  • ⚠️ Yellow — Inference exceeded 3 000 ms (consider using GPU or reducing image size)

Visual Pipeline Output — 4 Panels

Panel Description
Original Input Your uploaded PCB image
Defect Mask Binary (black/white) segmentation map — white regions are candidate defect areas
Anomaly Heatmap Red-tinted overlay on defect regions for quick visual inspection
Annotated Output ✅ Final image with color-coded bounding boxes and defect class labels

The annotated image is also displayed at full width below the four panels for detailed inspection.

Prediction Table

A table lists every detected defect with:

Column Content
# Detection index
Defect Class Color-coded badge (e.g., Missing Hole, Short)
Confidence Percentage with mini progress bar
Centroid (cx, cy) Pixel coordinates of the defect center
Bounding Box x, y, width, height in pixels

Class Distribution Chart

A bar chart summarizes the frequency of each defect type detected in the uploaded image.

Step 6 — Export Results

Four download buttons appear in the Export Results section:

Button Output File Contents
📥 Download Annotated Image pcb_annotated_<timestamp>.png Image with bounding boxes and labels
📥 Download CSV Log pcb_predictions_<timestamp>.csv All detections as a spreadsheet
📥 Download Defect Mask pcb_mask_<timestamp>.png Binary segmentation mask
📥 Download Evaluation Report pcb_eval_report_<timestamp>.txt Performance gate + full defect summary

Click any button to save the corresponding file to your browser's download location.

8. Understanding the Sidebar

Sidebar Element Description
PCB Defect AI logo Application branding
Model Path Text input to specify the .keras model file path
Pipeline Steps Visual numbered indicator of the 5 inference stages
Defect Classes Color-coded badge legend for all 6 defect types

9. Troubleshooting

❌ "Model not found at: ..."

Cause: The application launched before the model was trained.
Fix:

  1. Ensure the DeepPCB dataset is placed in Image Subtraction\DeepPCB_dataset\.
  2. Run run_pipeline.bat and wait for all stages to complete.
  3. Verify the file Model Training and Evaluation\module3_output\best_model.keras exists.
  4. Restart the app.

❌ No Defects Detected

Potential causes and fixes:

Cause Fix
Low-contrast image Use a higher-resolution, well-lit PCB photograph
Very uniform board Adaptive thresholding returns few anomalies on uniformly populated boards — inspect the mask panel
All contours filtered The detected regions may have been below the 80 px² minimum area — try a closer crop

⚠️ Inference Time Exceeds 3 Seconds

Cause Fix
Large image (>4 MP) Resize the image to 1–2 MP before uploading
CPU-only machine Install tensorflow-gpu if an NVIDIA GPU is available
First run (model cold load) Subsequent runs are faster due to model caching

❌ App Crashes on Launch

  1. Verify Python 3.12 is installed: py --version
  2. Confirm all dependencies installed: venv\Scripts\pip show streamlit
  3. Check requirements.txt installed cleanly with no error output.
  4. Review the terminal/command prompt for the full Python traceback.

❌ Stage 1 (Preprocessing) Fails — "Class folder not found"

  • Confirm the dataset is extracted to Image Subtraction\DeepPCB_dataset\.
  • Folder names are case-sensitive: Missing_hole, Mouse_bite, Open_circuit, Short, Spur, Spurious_copper.
  • Do not rename or restructure the dataset folders.

❌ Stage 2 (ROI Extraction) Produces Zero ROIs

  • Stage 2 reads from Image Subtraction\module1_output\ — ensure Stage 1 completed successfully.
  • Check that the defect_masks\ and aligned\ subfolders contain .png files.

10. Inference Pipeline Reference

For technical users, the complete execution flow during a single-image inference call is:

1. Decode uploaded bytes → OpenCV BGR array
2. Convert to grayscale → apply 5×5 median blur
3. Adaptive Gaussian thresholding (blockSize=31, C=8) → local anomaly map
4. Canny edge detection (low=40, high=160) → structural edge map
5. Bitwise OR (anomaly map + edge map) → combined binary map
6. Morphological closing (5×5) → fill defect blob holes
7. Morphological opening (3×3) → remove isolated noise pixels
8. findContours (RETR_EXTERNAL) → filter by area [80, 50000] px²
9. For each contour:
   a. Compute centroid (cx, cy) and bounding rectangle
   b. Crop 128×128 patch centred on (cx, cy)
   c. Normalize [0, 255] → [0.0, 1.0] float32
   d. Run EfficientNetB0 forward pass → 6-class softmax
   e. Record class name, confidence, full probability vector
10. Annotate original image with colored bounding boxes and class labels
11. Return results dict → display in UI → enable export

Typical runtime breakdown (CPU):

  • Steps 1–8: 20–50 ms
  • Step 9 (per contour): 30–80 ms
  • Step 10–11: < 5 ms