Initial commit

.clang-format

@@ -0,0 +1,39 @@
+AccessModifierOffset: -4
+AlignAfterOpenBracket: DontAlign
+AllowShortBlocksOnASingleLine: true
+AllowShortFunctionsOnASingleLine: All
+BasedOnStyle: LLVM
+BraceWrapping:
+  AfterClass: false
+  AfterControlStatement: false
+  AfterEnum: false
+  AfterFunction: false
+  AfterNamespace: false
+  AfterStruct: false
+  AfterUnion: false
+  BeforeCatch: true
+  BeforeElse: true
+  IndentBraces: false
+  SplitEmptyFunction: true
+  SplitEmptyRecord: true
+BreakBeforeBraces: Custom
+ColumnLimit: 0
+Cpp11BracedListStyle: false
+FixNamespaceComments: false
+IndentCaseLabels: false
+IndentPPDirectives: None
+IndentWidth: 4
+MaxEmptyLinesToKeep: 1
+NamespaceIndentation: All
+PointerAlignment: Right
+SortIncludes: false
+SortUsingDeclarations: false
+SpaceAfterCStyleCast: false
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeParens: ControlStatements
+SpaceInEmptyParentheses: false
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+TabWidth: 4
+UseTab: true

.gitattributes

@@ -1,2 +0,0 @@
-# Auto detect text files and perform LF normalization
-* text=auto

.gitignore

@@ -0,0 +1,55 @@
+# Build directories and files
+build/CMakeCache.txt
+build/cmake_install.cmake
+build/Makefile
+build/CMakeFiles/
+build/bin/
+
+# Compiled object files
+*.o
+*.obj
+
+# Compiled dynamic libraries
+*.so
+*.dylib
+*.dll
+
+# Compiled static libraries
+*.a
+*.lib
+
+# Executables
+*.exe
+*.out
+
+# CMake generated files
+CMakeCache.txt
+cmake_install.cmake
+Makefile
+CMakeFiles/
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# System files
+.DS_Store
+Thumbs.db
+
+# Temporary files
+*.tmp
+*.temp
+*.log
+
+# Don't ignore output images - these are the results we want to keep
+!build/*.jpg
+!build/*.png
+!build/*.bmp
+!build/*.tiff
+!build/*.tif
+
+# But still ignore the executable in bin directory
+build/bin/

CMakeLists.txt

@@ -0,0 +1,39 @@
+cmake_minimum_required(VERSION 3.10)
+project(avm)
+
+# Set C++ standard
+set(CMAKE_CXX_STANDARD 11)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# Set build type and optimization options
+set(CMAKE_BUILD_TYPE "Release")
+set(CMAKE_CXX_FLAGS "-O3")
+
+# Find OpenCV package
+find_package(OpenCV REQUIRED)
+
+# Print OpenCV information
+message(STATUS "OpenCV library status:")
+message(STATUS "    version: ${OpenCV_VERSION}")
+message(STATUS "    libraries: ${OpenCV_LIBS}")
+message(STATUS "    include path: ${OpenCV_INCLUDE_DIRS}")
+
+# Include OpenCV header files
+include_directories(${OpenCV_INCLUDE_DIRS})
+
+# Add header file directory
+include_directories(include)
+
+# Collect source files
+file(GLOB_RECURSE SOURCES "src/*.cpp")
+
+# Create executable file
+add_executable(avm ${SOURCES})
+
+# Link OpenCV libraries
+target_link_libraries(avm ${OpenCV_LIBS})
+
+# Set output directory
+set_target_properties(avm PROPERTIES
+    RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin"
+)

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Xi Xu
+
+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 without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,289 @@
+# AVM - Around View Monitoring System
+
+An OpenCV-based 360-degree surround view system that processes fisheye camera images to create a bird's eye view for vehicle parking assistance and navigation.
+
+## 🚀 Features
+
+- **Multi-Camera Fisheye Processing**: Supports 4 fisheye cameras (front, back, left, right)
+- **Automatic Corner Detection**: Uses advanced histogram-based algorithms for calibration board detection
+- **Real-time Undistortion**: Efficient fisheye-to-rectilinear image transformation
+- **Perspective Transformation**: Converts undistorted images to bird's eye view
+- **Seamless Stitching**: Blends multiple camera views into a single panoramic image
+- **Vehicle Overlay**: Adds vehicle model overlay for spatial reference
+
+## 🛠️ Installation
+
+### Prerequisites
+
+- **OpenCV 3.0+** (4.x recommended)
+- **CMake 3.10+**
+- **GCC/Clang** with C++11 support
+- **Linux/macOS/Windows** (WSL2 recommended for Windows)
+
+### Quick Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/xixu-me/AVM.git
+cd AVM
+
+# Make scripts executable
+chmod +x scripts/*.sh
+
+# Build the project
+./scripts/build.sh
+```
+
+For detailed installation instructions, see [INSTALLATION.md](docs/INSTALLATION.md).
+
+## 🚀 Quick Start
+
+### Run with Sample Data
+
+```bash
+# Execute the AVM system with provided sample images
+./scripts/run.sh
+```
+
+### Expected Output
+
+After successful execution, you'll find the following files in the `build/` directory:
+
+- `stitched_result_with_su7.jpg` - Final 360° panoramic view
+- `bird_*.jpg` - Individual bird's eye view images
+- `*_undis.jpg` - Undistorted fisheye images
+
+## 📸 Input Images
+
+The AVM system processes four fisheye camera images positioned around the vehicle:
+
+### Camera Configuration
+
+| Camera Position | File | Description |
+|----------------|------|-------------|
+| **Front** | `assets/images/front.png` | Front bumper center, covers front area |
+| **Back** | `assets/images/back.png` | Rear bumper center, covers rear area |
+| **Left** | `assets/images/left.png` | Left side mirror, covers left side |
+| **Right** | `assets/images/right.png` | Right side mirror, covers right side |
+
+### Sample Input Images
+
+<div align="center">
+
+| Front Camera | Back Camera |
+|:------------:|:-----------:|
+| ![Front View](assets/images/front.png) | ![Back View](assets/images/back.png) |
+| *Front fisheye camera capturing forward area* | *Rear fisheye camera capturing backward area* |
+
+| Left Camera | Right Camera |
+|:-----------:|:------------:|
+| ![Left View](assets/images/left.png) | ![Right View](assets/images/right.png) |
+| *Left side fisheye camera* | *Right side fisheye camera* |
+
+</div>
+
+### Input Image Specifications
+
+- **Resolution**: 1280×960 pixels
+- **Format**: PNG/JPG
+- **Camera Type**: Fisheye lens with wide FOV
+- **Calibration**: 2×4 rectangular grid pattern visible in each image
+- **Bit Depth**: 8-bit RGB
+
+### Calibration Board Requirements
+
+Each input image must contain a **2×4 rectangular calibration pattern**:
+
+- **Grid Size**: 2 rows × 4 columns (8 corners total)
+- **Visibility**: Pattern must be clearly visible in overlapping areas
+- **Contrast**: High contrast between pattern and ground
+- **Position**: Within the valid detection region (20%-70% of image height)
+
+## 🎯 Output Images
+
+The AVM system generates multiple intermediate and final output images:
+
+### Processing Pipeline Outputs
+
+<div align="center">
+
+| Stage | Description | Example |
+|-------|-------------|---------|
+| **1. Undistorted Images** | Fisheye correction applied | ![Undistorted](build/front_undis.jpg) |
+| **2. Bird's Eye View** | Perspective transformation | ![Bird's Eye](build/bird_front_2.jpg) |
+| **3. Final Stitched Result** | Complete 360° view | ![Final Result](build/stitched_result_with_su7.jpg) |
+
+</div>
+
+### Final Output Visualization
+
+The final stitched image provides a complete 360-degree around view:
+
+<div align="center">
+<img src="build/stitched_result_with_su7.jpg" alt="Final AVM Output" width="800"/>
+<p><em>Complete 360° Around View Monitor output with vehicle overlay</em></p>
+</div>
+
+### Output Image Details
+
+#### 1. Undistorted Images (`*_undis.jpg`)
+
+- **Purpose**: Corrected fisheye distortion
+- **Resolution**: 1280×960 pixels
+- **Features**: Corner points marked, distortion removed
+
+#### 2. Bird's Eye View Images (`bird_*.jpg`)
+
+- **Front/Back Views**: 792×305 pixels
+- **Left/Right Views**: 1131×281 pixels
+- **Perspective**: Top-down view transformation
+- **Rotation**: Automatically corrected for proper orientation
+
+#### 3. Debug Images
+
+- **Contrast Enhanced** (`*_img_contrast.jpg`): Gamma-corrected for corner detection
+- **Thresholded** (`*_img_thresh.jpg`): Binary images showing detected features
+- **Corner Detection** (`*_undis_1.jpg`): Undistorted images with detected corners marked
+
+#### 4. Final Stitched Image (`stitched_result_with_su7.jpg`)
+
+- **Composition**: All four camera views seamlessly blended
+- **Vehicle Overlay**: Su7 vehicle model positioned at center
+- **Dimensions**: Variable based on camera layout
+- **Blending**: Smooth transitions using mask images
+
+## 🏗️ System Architecture
+
+### Processing Pipeline
+
+```
+[Fisheye Images] → [Undistortion] → [Corner Detection] → [Bird's Eye Transform] → [Image Stitching] → [Final Output]
+```
+
+### Key Components
+
+1. **Undistortion Engine**: Converts fisheye to rectilinear projection
+2. **Corner Detector**: Histogram-based calibration pattern detection
+3. **Perspective Transform**: Homography-based bird's eye view generation  
+4. **Image Stitcher**: Mask-based seamless image blending
+
+### Camera Model
+
+The system uses a polynomial fisheye distortion model:
+
+```
+θ_distorted = θ_undistorted + k₁θ³ + k₂θ⁵ + k₃θ⁷ + k₄θ⁹
+```
+
+Default parameters optimized for automotive fisheye cameras.
+
+## ⚙️ Configuration
+
+### Camera Parameters
+
+Key parameters that can be adjusted in `src/avm.cpp`:
+
+```cpp
+// Camera intrinsics
+float m_focal_length = 910.0;      // Camera focal length (pixels)
+float m_fish_scale = 0.5;          // Fisheye scaling factor
+float m_undis_scale = 1.55;        // Undistortion scaling
+
+// Distortion coefficients
+cv::Vec4d distortion_coeffs = {
+    -0.05611147,  // k1
+    -0.05377447,  // k2
+     0.0115717,   // k3
+     0.0030788    // k4
+};
+```
+
+### Layout Configuration
+
+```cpp
+#define IMAGE_BACK_PIXEL_Y 643   // Back image Y offset
+#define IMAGE_RIGHT_PIXEL_X 398  // Right image X offset
+```
+
+### Using Custom Images
+
+1. **Replace Input Images**: Place your fisheye images in `assets/images/`
+2. **Name Convention**: Use `front.png`, `back.png`, `left.png`, `right.png`
+3. **Calibration Pattern**: Ensure 2×4 grid is visible in overlapping areas
+4. **Adjust Parameters**: Modify camera parameters if using different lenses
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+#### Build Errors
+
+```bash
+# OpenCV not found
+sudo apt-get install libopencv-dev libopencv-contrib-dev
+
+# CMake version too old
+wget https://cmake.org/files/v3.20/cmake-3.20.0-linux-x86_64.sh
+```
+
+#### Runtime Issues
+
+```bash
+# Missing input images
+cp your_images/* assets/images/
+
+# Permission denied
+chmod +x scripts/*.sh
+```
+
+#### Corner Detection Failures
+
+- Ensure calibration board has high contrast
+- Check that pattern is within valid detection region
+- Verify image quality and lighting conditions
+
+### Debug Mode
+
+Enable debug output by modifying the source code:
+
+```cpp
+#define DEBUG_MODE 1  // Add this line for debug output
+```
+
+## 📊 Performance
+
+### Typical Processing Times
+
+- **Image Loading**: ~10ms per image
+- **Undistortion**: ~50ms per image  
+- **Corner Detection**: ~100-200ms per image
+- **Stitching**: ~100ms total
+- **Overall**: ~1-2 seconds for complete pipeline
+
+### Memory Usage
+
+- **Peak Memory**: ~30-40MB
+- **Input Images**: ~5MB total
+- **Intermediate Results**: ~20MB
+- **Output Images**: ~2-3MB
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- OpenCV community for excellent computer vision library
+- Contributors to fisheye camera calibration algorithms
+- Automotive industry standards for AVM system requirements
+
+## 📞 Support
+
+- **Documentation**: Check [docs/](docs/) directory for detailed guides
+
+---
+
+<div align="center">
+<p>Made with ❤️ for safer driving</p>
+<p>⭐ Star this repo if you find it helpful!</p>
+</div>

docs/INSTALLATION.md

@@ -0,0 +1,280 @@
+# Installation Guide
+
+## System Requirements
+
+### Operating System
+
+- Linux (Ubuntu 18.04+, CentOS 7+)
+- macOS 10.14+
+- Windows 10+ (with WSL2 recommended)
+
+### Hardware Requirements
+
+- **Memory**: Minimum 4GB RAM, recommended 8GB+
+- **Storage**: 1GB free space for build and outputs
+- **CPU**: Multi-core processor recommended for optimal performance
+
+## Dependencies
+
+### Required Dependencies
+
+#### OpenCV (Version 3.0+)
+
+OpenCV is the core dependency for image processing operations.
+
+**Ubuntu/Debian:**
+
+```bash
+sudo apt update
+sudo apt install libopencv-dev libopencv-contrib-dev
+```
+
+**CentOS/RHEL:**
+
+```bash
+sudo yum install opencv-devel
+# or for newer versions:
+sudo dnf install opencv-devel
+```
+
+**macOS (using Homebrew):**
+
+```bash
+brew install opencv
+```
+
+**Manual Installation:**
+If package managers don't provide a recent enough version:
+
+```bash
+# Download OpenCV source
+git clone https://github.com/opencv/opencv.git
+cd opencv
+git checkout 4.x  # or your preferred version
+
+# Build and install
+mkdir build && cd build
+cmake -D CMAKE_BUILD_TYPE=RELEASE \
+      -D CMAKE_INSTALL_PREFIX=/usr/local \
+      -D WITH_TBB=ON \
+      -D WITH_V4L=ON \
+      -D WITH_QT=OFF \
+      -D WITH_OPENGL=ON \
+      ..
+make -j$(nproc)
+sudo make install
+```
+
+#### CMake (Version 3.10+)
+
+Required for building the project.
+
+**Ubuntu/Debian:**
+
+```bash
+sudo apt install cmake
+```
+
+**CentOS/RHEL:**
+
+```bash
+sudo yum install cmake
+# or: sudo dnf install cmake
+```
+
+**macOS:**
+
+```bash
+brew install cmake
+```
+
+### Optional Dependencies
+
+#### Git (for version control)
+
+```bash
+# Ubuntu/Debian
+sudo apt install git
+
+# CentOS/RHEL  
+sudo yum install git
+
+# macOS
+git --version  # Usually pre-installed
+```
+
+## Installation Steps
+
+### Method 1: Clone from GitHub (Recommended)
+
+```bash
+# Clone the repository
+git clone https://github.com/xixu-me/AVM.git
+cd AVM
+
+# Make scripts executable
+chmod +x scripts/*.sh
+
+# Build the project
+./scripts/build.sh
+```
+
+### Method 2: Download and Build
+
+```bash
+# Download and extract source code
+wget https://github.com/xixu-me/AVM/archive/main.zip
+unzip main.zip
+cd AVM-main
+
+# Make scripts executable
+chmod +x scripts/*.sh
+
+# Build the project
+./scripts/build.sh
+```
+
+### Manual Build Process
+
+If you prefer to build manually:
+
+```bash
+# Create build directory
+mkdir -p build
+cd build
+
+# Configure with CMake
+cmake ..
+
+# Build (adjust -j flag based on your CPU cores)
+make -j$(nproc)
+
+# Verify build
+ls bin/avm  # Should exist if build successful
+```
+
+## Verification
+
+### Test Installation
+
+```bash
+# Quick test with provided sample images
+./scripts/run.sh
+
+# Check output
+ls build/stitched_result_with_su7.jpg  # Should exist after successful run
+```
+
+### Expected Output Files
+
+After successful execution, you should see:
+
+```
+build/
+├── front_undis.jpg         # Undistorted front view
+├── back_undis.jpg          # Undistorted back view  
+├── left_undis.jpg          # Undistorted left view
+├── right_undis.jpg         # Undistorted right view
+├── bird_front_2.jpg        # Front bird's eye view
+├── bird_back_2.jpg         # Back bird's eye view
+├── bird_left_2.jpg         # Left bird's eye view
+├── bird_right_2.jpg        # Right bird's eye view
+└── stitched_result_with_su7.jpg  # Final panoramic result
+```
+
+## Troubleshooting
+
+### OpenCV Not Found
+
+```
+CMake Error: Could not find OpenCV
+```
+
+**Solution:**
+
+- Verify OpenCV installation: `pkg-config --modversion opencv`
+- Set OpenCV path manually: `export OpenCV_DIR=/path/to/opencv`
+- Reinstall OpenCV development packages
+
+### Build Errors
+
+```
+error: opencv2/opencv.hpp: No such file or directory
+```
+
+**Solution:**
+
+- Install OpenCV development headers
+- Check include paths in CMakeLists.txt
+- Verify compiler can find OpenCV includes
+
+### Runtime Errors
+
+```
+error while loading shared libraries: libopencv_core.so
+```
+
+**Solution:**
+
+- Update library path: `sudo ldconfig`
+- Add to LD_LIBRARY_PATH: `export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH`
+
+### Permission Errors
+
+```
+Permission denied: ./scripts/build.sh
+```
+
+**Solution:**
+
+```bash
+chmod +x scripts/*.sh
+```
+
+### Missing Input Images
+
+```
+[ERROR] Unable to read input image files
+```
+
+**Solution:**
+
+- Ensure input images exist in `assets/images/`
+- Check file permissions and formats (PNG/JPG supported)
+- Verify image files are not corrupted
+
+## Performance Optimization
+
+### Build Optimizations
+
+For maximum performance, build in Release mode:
+
+```bash
+cd build
+cmake -DCMAKE_BUILD_TYPE=Release ..
+make -j$(nproc)
+```
+
+### Runtime Optimizations
+
+- Use SSD storage for faster I/O operations
+- Ensure sufficient RAM to avoid swapping
+- Close unnecessary applications during processing
+
+## Next Steps
+
+After successful installation:
+
+1. **Read the Documentation**: Check `README.md` for usage instructions
+2. **Try Custom Images**: Replace sample images with your own fisheye images
+3. **Explore Configuration**: Review camera parameters in the source code
+4. **Contribute**: See `CONTRIBUTING.md` for development guidelines
+
+## Getting Help
+
+If you encounter issues:
+
+1. Check this troubleshooting section
+2. Search existing GitHub issues
+3. Create a new issue with detailed error information
+4. Include your system information and build logs

docs/SAMPLE_DATA.md

@@ -0,0 +1,115 @@
+# Sample Data Description
+
+## Input Images Overview
+
+The AVM system comes with sample fisheye camera images that demonstrate the complete processing pipeline.
+
+### Image Specifications
+
+- **Resolution**: 1280×960 pixels
+- **Format**: PNG
+- **Camera Type**: Fisheye lens with wide field of view
+- **Calibration Pattern**: 2×4 rectangular grid visible in each image
+
+### Camera Positions
+
+#### Front Camera (`assets/images/front.png`)
+
+- Position: Front bumper center
+- Field of view: Covers front area and left/right sides
+- Calibration board: Positioned on ground in front of vehicle
+
+#### Back Camera (`assets/images/back.png`)
+
+- Position: Rear bumper center  
+- Field of view: Covers rear area and left/right sides
+- Calibration board: Positioned on ground behind vehicle
+
+#### Left Camera (`assets/images/left.png`)
+
+- Position: Left side mirror or door
+- Field of view: Covers left side area
+- Calibration board: Positioned on ground to the left of vehicle
+
+#### Right Camera (`assets/images/right.png`)
+
+- Position: Right side mirror or door
+- Field of view: Covers right side area
+- Calibration board: Positioned on ground to the right of vehicle
+
+### Vehicle Model
+
+#### Vehicle Overlay (`assets/images/su7.png`)
+
+- **Type**: Top-down vehicle silhouette
+- **Format**: PNG with alpha channel for transparency
+- **Usage**: Overlaid on final stitched result to show vehicle position
+- **Positioning**: Automatically centered in panoramic view
+
+### Mask Images
+
+The system uses blending masks to create smooth transitions between camera views:
+
+#### Mask Specifications
+
+- **Location**: `assets/masks/`
+- **Files**:
+  - `maskFront.jpg` - Front camera blending mask
+  - `maskBack.jpg` - Back camera blending mask
+  - `maskLeft.jpg` - Left camera blending mask
+  - `maskRight.jpg` - Right camera blending mask
+- **Purpose**: Define blending regions for seamless image stitching
+- **Format**: Grayscale images where brightness indicates blending weight
+
+### Calibration Board Details
+
+#### Pattern Configuration
+
+- **Grid Size**: 2 rows × 4 columns
+- **Corner Count**: 8 total corners
+- **Board Size**: Approximately 50cm × 100cm (physical dimensions)
+- **Visibility**: Clearly visible in all four camera views
+
+#### Detection Requirements
+
+- **Contrast**: High contrast between board and ground
+- **Lighting**: Even illumination without shadows
+- **Position**: Fully within camera field of view
+- **Orientation**: Rectangular pattern aligned with vehicle axes
+
+## Using Your Own Images
+
+### Camera Setup Requirements
+
+To use your own images with the AVM system:
+
+1. **Camera Positioning**:
+   - Install fisheye cameras at four positions around vehicle
+   - Ensure overlapping fields of view between adjacent cameras
+   - Maintain consistent height and angle
+
+2. **Calibration Board**:
+   - Create a 2×4 rectangular calibration pattern
+   - Position board in overlapping areas between camera views
+   - Ensure board is flat and clearly visible
+
+3. **Image Capture**:
+   - Capture images simultaneously from all four cameras
+   - Maintain consistent lighting conditions
+   - Ensure calibration board is visible in each image
+
+4. **File Preparation**:
+   - Save images as PNG or JPG format
+   - Name files: `front.png`, `back.png`, `left.png`, `right.png`
+   - Place in `assets/images/` directory
+
+### Camera Parameter Adjustment
+
+If using different cameras, you may need to adjust parameters in the source code:
+
+- **Focal Length**: Modify based on your camera specifications
+- **Distortion Coefficients**: Calibrate using OpenCV calibration tools
+- **Image Resolution**: Update if using different image sizes
+- **Fisheye Scale Factor**: Adjust based on lens characteristics
+
+For detailed parameter tuning, refer to the [Technical Specifications](TECHNICAL_SPECS.md).

docs/TECHNICAL_SPECS.md

@@ -0,0 +1,133 @@
+# Technical Specifications
+
+## Camera Parameters
+
+### Fisheye Camera Specifications
+
+- **Focal Length**: 910.0 pixels
+- **Pixel Size**: 3.0μm × 3.0μm
+- **Image Resolution**: 1280×960 pixels
+- **Fisheye Scaling Factor**: 0.5
+- **Undistortion Scaling**: 1.55
+
+### Distortion Model
+
+The system uses a polynomial fisheye distortion model:
+
+```
+θ_distorted = θ_undistorted + k₁θ³ + k₂θ⁵ + k₃θ⁷ + k₄θ⁹
+```
+
+Default distortion coefficients:
+
+- k₁ = -0.05611147
+- k₂ = -0.05377447
+- k₃ = 0.0115717
+- k₄ = 0.0030788
+
+## Calibration Board Specifications
+
+### Pattern Configuration
+
+- **Pattern Type**: Rectangular grid
+- **Grid Size**: 2×4 (2 rows, 4 columns)
+- **Corner Count**: 8 corners total
+- **Detection Method**: Histogram-based adaptive thresholding
+
+### Detection Parameters
+
+- **Contrast Enhancement**: 2.5× gamma correction
+- **Valid Detection Region**: Y-axis 20%-70% of image height
+- **Corner Refinement**: Sub-pixel accuracy using `cornerSubPix`
+- **Backup Detection**: Adaptive threshold with 401×401 kernel
+
+## Bird's Eye View Parameters
+
+### Image Dimensions
+
+- **Front/Back Views**: 792×305 pixels
+- **Left/Right Views**: 1131×281 pixels
+- **Final Stitched Image**: Variable based on layout
+
+### Transformation Matrices
+
+Each camera view uses homography transformation calculated from:
+
+- Source: Detected corner points in undistorted image
+- Target: Predefined bird's eye view coordinates
+
+### Rotation Corrections
+
+- **Front View**: 0° (no rotation)
+- **Back View**: 180°
+- **Left View**: 90° clockwise
+- **Right View**: 90° counter-clockwise
+
+## Image Stitching Parameters
+
+### Layout Configuration
+
+- **Back Image Offset**: Y = 643 pixels
+- **Right Image Offset**: X = 398 pixels
+- **Vehicle Overlay**: Center positioned with alpha blending
+
+### Blending Masks
+
+- Individual masks for each camera view
+- Smooth transition zones between adjacent views
+- Alpha channel support for vehicle model overlay
+
+## Performance Characteristics
+
+### Processing Pipeline Timing
+
+1. **Image Loading**: ~10ms per image
+2. **Undistortion**: ~50ms per image
+3. **Corner Detection**: ~100-200ms per image
+4. **Perspective Transform**: ~30ms per image
+5. **Image Stitching**: ~100ms total
+
+### Memory Requirements
+
+- **Input Images**: ~5MB (4 × 1280×960×3)
+- **Intermediate Results**: ~20MB
+- **Output Image**: ~2-3MB
+- **Total Peak Usage**: ~30-40MB
+
+## Algorithm Details
+
+### Corner Detection Algorithm
+
+1. **Preprocessing**:
+   - Convert to grayscale
+   - Apply gamma correction for contrast enhancement
+   - Set valid detection region (20%-70% Y-axis)
+
+2. **Binarization**:
+   - Histogram analysis for optimal threshold
+   - Bimodal distribution detection
+   - Adaptive fallback if histogram method fails
+
+3. **Contour Analysis**:
+   - Find contours in binary image
+   - Filter by area (minimum threshold)
+   - Approximate polygonal shapes
+
+4. **Rectangle Validation**:
+   - Verify 4-sided polygon structure
+   - Check geometric constraints
+   - Sort corners in consistent order
+
+5. **Coordinate Transformation**:
+   - Transform from fisheye to undistorted coordinates
+   - Apply sub-pixel refinement
+   - Validate final corner positions
+
+### Homography Calculation
+
+Uses OpenCV's `findHomography` with:
+
+- **Method**: Direct Linear Transform (DLT)
+- **Source Points**: 8 detected corners
+- **Target Points**: Predefined bird's eye coordinates
+- **Robustness**: No RANSAC (assumes clean input)

scripts/build.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+
+# Build script for avm AVM project
+# This script builds the OpenCV-based Around View Monitoring system
+
+set -e # Exit on any error
+
+echo "=== Building avm AVM Project ==="
+
+# Get the project root directory (parent of scripts directory)
+PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$PROJECT_ROOT"
+
+# Check if we're in the right directory
+if [ ! -f "CMakeLists.txt" ]; then
+    echo "Error: CMakeLists.txt not found. Please run this script from the project root directory."
+    exit 1
+fi
+
+# Check if OpenCV is installed
+if ! pkg-config --exists opencv4 && ! pkg-config --exists opencv; then
+    echo "Error: OpenCV not found. Please install OpenCV development packages."
+    echo "On Ubuntu/Debian: sudo apt-get install libopencv-dev"
+    exit 1
+fi
+
+# Display OpenCV version
+OPENCV_VERSION=$(pkg-config --modversion opencv4 2>/dev/null || pkg-config --modversion opencv 2>/dev/null)
+echo "Found OpenCV version: $OPENCV_VERSION"
+
+# Create build directory if it doesn't exist
+if [ ! -d "build" ]; then
+    echo "Creating build directory..."
+    mkdir build
+fi
+
+# Change to build directory
+cd build
+
+# Configure with CMake
+echo "Configuring with CMake..."
+cmake ..
+
+# Build the project
+echo "Building project..."
+make -j$(nproc)
+
+# Check if build was successful
+if [ -f "bin/avm" ]; then
+    echo "=== Build completed successfully! ==="
+    echo "Executable created: build/bin/avm"
+else
+    echo "=== Build failed! ==="
+    exit 1
+fi

scripts/clean.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+
+# Cleanup script for avm AVM project
+# This script removes all generated output files and build artifacts
+
+set -e # Exit on any error
+
+# Get the project root directory (parent of scripts directory)
+PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$PROJECT_ROOT"
+
+echo "=== Cleaning up avm AVM Project ==="
+
+# List of generated output files to remove
+OUTPUT_FILES=(
+    "stitched_result_with_su7.jpg"
+    "bird_front.jpg"
+    "bird_back.jpg"
+    "bird_left.jpg"
+    "bird_right.jpg"
+    "bird_front_2.jpg"
+    "bird_back_2.jpg"
+    "bird_left_2.jpg"
+    "bird_right_2.jpg"
+    "front_img_contrast.jpg"
+    "back_img_contrast.jpg"
+    "left_img_contrast.jpg"
+    "right_img_contrast.jpg"
+    "front_img_thresh.jpg"
+    "back_img_thresh.jpg"
+    "left_img_thresh.jpg"
+    "right_img_thresh.jpg"
+    "front_undis_1.jpg"
+    "back_undis_1.jpg"
+    "left_undis_1.jpg"
+    "right_undis_1.jpg"
+    "front_undis.jpg"
+    "back_undis.jpg"
+    "left_undis.jpg"
+    "right_undis.jpg"
+)
+
+# Remove generated output files
+echo "Removing generated output files..."
+REMOVED_COUNT=0
+for file in "${OUTPUT_FILES[@]}"; do
+    if [ -f "$file" ]; then
+        rm "$file"
+        echo "  Removed: $file"
+        REMOVED_COUNT=$((REMOVED_COUNT + 1))
+    fi
+done
+
+if [ $REMOVED_COUNT -eq 0 ]; then
+    echo "  No generated output files found to remove."
+else
+    echo "  Removed $REMOVED_COUNT output files."
+fi
+
+# Remove build directory and all build artifacts
+if [ -d "build" ]; then
+    echo "Removing build directory..."
+    rm -rf build
+    echo "  Removed: build/ directory and all build artifacts"
+else
+    echo "  Build directory not found (already clean)."
+fi
+
+echo ""
+echo "To rebuild and run the project:"
+echo "  ./build.sh"
+echo "  ./run.sh"

scripts/run.sh

@@ -0,0 +1,94 @@
+#!/bin/bash
+
+# Run script for avm AVM project
+# This script runs the Around View Monitoring system
+
+set -e # Exit on any error
+
+# Get the project root directory (parent of scripts directory)
+PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$PROJECT_ROOT"
+
+echo "=== Running avm AVM System ==="
+
+# Check if executable exists
+if [ ! -f "build/bin/avm" ]; then
+    echo "Error: avm executable not found."
+    echo "Please run the build script first: ./scripts/build.sh"
+    exit 1
+fi
+
+# Check if required input images exist
+REQUIRED_IMAGES=("assets/images/front.png" "assets/images/back.png" "assets/images/left.png" "assets/images/right.png")
+MISSING_IMAGES=()
+
+for img in "${REQUIRED_IMAGES[@]}"; do
+    if [ ! -f "$img" ]; then
+        MISSING_IMAGES+=("$img")
+    fi
+done
+
+if [ ${#MISSING_IMAGES[@]} -gt 0 ]; then
+    echo "Warning: Some required input images are missing:"
+    for img in "${MISSING_IMAGES[@]}"; do
+        echo "  - $img"
+    done
+    echo "The program may not work correctly without all input images."
+    echo ""
+fi
+
+# Check if mask images exist
+MASK_IMAGES=("assets/masks/maskFront.jpg" "assets/masks/maskBack.jpg" "assets/masks/maskLeft.jpg" "assets/masks/maskRight.jpg")
+MISSING_MASKS=()
+
+for mask in "${MASK_IMAGES[@]}"; do
+    if [ ! -f "$mask" ]; then
+        MISSING_MASKS+=("$mask")
+    fi
+done
+
+if [ ${#MISSING_MASKS[@]} -gt 0 ]; then
+    echo "Warning: Some required mask images are missing:"
+    for mask in "${MISSING_MASKS[@]}"; do
+        echo "  - $mask"
+    done
+    echo "The final stitching may not work correctly without all mask images."
+    echo ""
+fi
+
+# Check if su7.png exists for final overlay
+if [ ! -f "assets/images/su7.png" ]; then
+    echo "Warning: su7.png overlay image is missing. Final image will not include the car overlay."
+    echo ""
+fi
+
+echo "Starting AVM processing..."
+echo "This will:"
+echo "1. Detect corner points in fisheye camera images"
+echo "2. Apply undistortion and perspective transformation"
+echo "3. Generate bird's eye view images"
+echo "4. Stitch images together with masks"
+echo "5. Create final 360-degree around view image"
+echo ""
+
+# Run the program
+./build/bin/avm
+
+# Check if output was generated
+if [ -f "build/stitched_result_with_su7.jpg" ]; then
+    echo ""
+    echo "=== AVM Processing completed successfully! ==="
+    echo ""
+    echo "Generated output files:"
+    echo "  - build/stitched_result_with_su7.jpg (Final stitched image)"
+    echo "  - build/bird_front_2.jpg, build/bird_back_2.jpg, build/bird_left_2.jpg, build/bird_right_2.jpg (Bird's eye views)"
+    echo "  - build/*_img_contrast.jpg (Contrast enhanced images)"
+    echo "  - build/*_img_thresh.jpg (Thresholded images with detected points)"
+    echo "  - build/*_undis_1.jpg (Undistorted images with corner points)"
+    echo ""
+    echo "You can view the final result: build/stitched_result_with_su7.jpg"
+else
+    echo "=== Warning: Expected output file not found ==="
+    echo "The program completed but build/stitched_result_with_su7.jpg was not generated."
+    echo "This might be due to missing input files or processing errors."
+fi