Fix(Finding_Lanes): Dynamic ROI, slope filtering, multi-source CLI, visualizer, unit tests & docs (#467)

Finding_Lanes/README.md

@@ -2,31 +2,130 @@
 ![Star Badge](https://img.shields.io/static/v1?label=%F0%9F%8C%9F&message=If%20Useful&style=style=flat&color=BC4E99)
 ![Open Source Love](https://badges.frapsoft.com/os/v1/open-source.svg?v=103)
 
-# <b>🚘 Finding Lanes </b>
-### Let's go!
-<img src="https://media3.giphy.com/media/8QC4kjqN9qDEk/giphy.gif?cid=ecf05e471kl80anlf7s2wx2yz9v5ssu5xxgkbsxq74j9afql&rid=giphy.gif&ct=g">
+# ?? Finding Lanes
 
-## 🛠️ <b> Description </b>
-A short description about the script must be mentioned here.
+> Real-time and static road lane boundary detection using OpenCV and NumPy.
 
-## ⚙️ <b>Languages or Frameworks Used
-Run the following command: 
+<p align="center">
+  <img src="capture.png" width="80%" alt="Finding Lanes Demo">
+</p>
+
+## ??? Description
+
+**Finding Lanes** is a modular Python computer vision project that detects and highlights road lane boundaries from static images, video files, or live camera feeds. 
+
+The pipeline processes each frame through several standard computer vision stages:
+1. **Grayscale Conversion & Gaussian Blur**: Reduces image noise and gradient variance.
+2. **Canny Edge Detection**: Identifies sharp brightness transitions indicating potential lane boundaries.
+3. **Dynamic Region of Interest (ROI)**: Dynamically computes a triangular polygon mask proportional to frame dimensions to eliminate irrelevant road surroundings and sky.
+4. **Hough Transform Line Detection (`cv2.HoughLinesP`)**: Identifies line segments from edge pixels.
+5. **Slope-Intercept Regression & Extrapolation**: Separates left (negative slope) and right (positive slope) line segments, filters out horizontal noise markings, and extrapolates continuous lane boundary lines.
+6. **Alpha Blending (`cv2.addWeighted`)**: Overlays highlighted lane boundaries onto the original frame.
+
+---
+
+## ? Features
+
+- **Dynamic ROI**: Adapts automatically to arbitrary image/video resolutions and aspect ratios.
+- **Robust Line Filtering**: Ignores horizontal markings and guards against zero-division, `NaN`, or out-of-bound coordinates.
+- **Multi-Source Support**: Seamlessly processes static images (`picture.jpg`), video files (`video.mp4`), or live camera streams (`--camera 0`).
+- **Headless & Batch Support**: `--no-show` flag and `--output` options for saving results in automated/CI pipelines.
+- **Pipeline Visualizer (`sub.py`)**: 4-panel subplot showing Original, Canny Edges, ROI Masked, and Lane Detection stages side-by-side.
+- **Comprehensive Unit Tests (`test_lanes.py`)**: 100% test coverage over all core pipeline functions and edge cases.
+
+---
+
+## ?? Requirements & Installation
+
+Ensure you have Python 3.8+ installed. Install the required dependencies:
+
+```sh
+pip install -r requirements.txt
+```
+
+Or install dependencies manually:
+
+```sh
+pip install opencv-python numpy matplotlib
+```
+
+---
+
+## ?? How to Run
+
+Navigate to the project folder:
+
+```sh
+cd Finding_Lanes
+```
+
+### 1. Run Lane Detection on Video (Default)
+```sh
+python lanes.py
+```
+> Press **`q`** on the video window to quit.
+
+### 2. Run Lane Detection on a Static Image
+```sh
+python lanes.py --image picture.jpg
+```
+
+### 3. Run on Custom Video and Save Output
+```sh
+python lanes.py --video path/to/video.mp4 --output output.mp4
+```
+
+### 4. Run on Live Webcam
+```sh
+python lanes.py --camera 0
+```
+
+### 5. Multi-Stage Pipeline Visualizer (`sub.py`)
+To inspect intermediate computer vision stages side-by-side using Matplotlib:
+```sh
+python sub.py
+```
+Or with custom image and save output:
 ```sh
-$ python -m pip install --upgrade pip
-$ python -m pip install opencv-python
+python sub.py --image picture.jpg --output pipeline_stages.png
 ```
-## <img src="https://cdn-icons-png.flaticon.com/512/109/109197.png" width="30" height="30"> <b>How to run</b>
-open a terminal in the folder where your script is located and run the following command:
+
+---
+
+## ?? Running Unit Tests
+
+Run the test suite using Python's built-in `unittest` runner:
+
 ```sh
-$ python lanes.py
+python -m unittest test_lanes.py -v
+```
+
+---
+
+## ?? Project Structure
+
 ```
-## <img src="https://cdn-icons-png.flaticon.com/512/61/61180.png" width="30" height="30"><b> How to close</b>
+Finding_Lanes/
+??? README.md          # Project documentation and guide
+??? lanes.py           # Core lane detection engine and CLI
+??? sub.py             # 4-stage pipeline visualization utility
+??? test_lanes.py      # Unit test suite
+??? picture.jpg        # Sample input road image
+??? video.mp4          # Sample input road driving video
+??? capture.png        # Demo output screenshot
+```
+
+---
+
+## ?? Demo
 
-Just press q
+<p align="center">
+  <img src="capture.png" width="100%" alt="Finding Lanes Demo Output">
+</p>
 
-## 📺 <b> Demo </b>
+---
 
-<img src="Finding_Lanes/capture.png" width=100% height=100%>
+## ?? Author
 
-## 🤖 <b> Author</b>
-zmdlw (https://github.com/zmdlw)
+- Original Script: **zmdlw** ([@zmdlw](https://github.com/zmdlw))
+- Enhancements & Tests: **Prayas Dey** ([@Prayas340](https://github.com/Prayas340))