avm/docs/INSTALLATION.md

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:

sudo apt update
sudo apt install libopencv-dev libopencv-contrib-dev

CentOS/RHEL:

sudo yum install opencv-devel
# or for newer versions:
sudo dnf install opencv-devel

macOS (using Homebrew):

brew install opencv

Manual Installation: If package managers don't provide a recent enough version:

# 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:

sudo apt install cmake

CentOS/RHEL:

sudo yum install cmake
# or: sudo dnf install cmake

macOS:

brew install cmake

Optional Dependencies

Git (for version control)

# 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)

# 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

# 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:

# 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

# 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:

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:

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