PyAutoScan

A Python-based Windows scanning automation tool for printer/scanner devices using WIA.

PyAutoScan simplifies the process of scanning documents with HP and other printer devices that support WIA (Windows Image Acquisition). It provides:

• One-click auto-scan with customizable quality (low/medium/high)
• Image-to-PDF conversion for multi-page documents
• Configurable settings via scan_config.ini (resolution, color mode, auto-crop, deskew, output folder, etc.)
• Automatic file naming with timestamps
• Scanner info extraction (model, driver properties, max resolution, supported features)
• Optional auto-crop & deskew for cleaner scans

Works with HP and other multi-function printer devices (MFP) that expose their scanner through WIA.

🚀 Quick Start

# Clone the repository
git clone https://github.com/Pandiyarajk/pyautoscan.git
cd pyautoscan

# Install dependencies
pip install -r requirements.txt

# Test scanner connection
python scanner_info.py

# Start scanning
python basic_scan.py

🚀 Features

• Basic Scanning: Simple, fast scanning with configurable quality and format options
• Advanced Scanning: Enhanced scanning with auto-crop and deskew capabilities
• Multiple Formats: Support for JPG, PNG, TIFF, and PDF output
• Quality Control: Configurable DPI settings (150, 300, 600)
• Scanner Detection: Automatic scanner detection and information display
• Configuration Management: INI-based configuration for easy customization
• PDF Conversion: Convert multiple images to single PDF documents
• Windows Integration: Native Windows WIA (Windows Image Acquisition) support

📋 Requirements

• Windows 10/11
• Python 3.7+ (Tested on Python 3.13)
• Compatible scanner with WIA drivers (Tested on HP Printer scanner features)
• Required Python packages (see requirements.txt)

📋 Dependencies

• pywin32: Windows COM integration for WIA
• Pillow: Image processing and PDF creation
• powerlogger: Enhanced logging with Rich console output and file rotation

🛠️ Installation

Option 1: Clone from GitHub

1. Clone the repository:

   git clone https://github.com/Pandiyarajk/pyautoscan.git
   cd pyautoscan

2. Install dependencies:

   pip install -r requirements.txt

3. Verify scanner connection:

   python scanner_info.py

Option 2: Install via pip (when published to PyPI)

pip install pyautoscan

Option 3: Download Release

Download the latest release from GitHub Releases for pre-built Windows executables.

📖 Usage

Basic Scanning

python basic_scan.py

Advanced Scanning

python advanced_scan.py

Scanner Information

python scanner_info.py

Configuration

Edit scan_config.ini to customize:

• Output directory
• File format preferences
• Quality settings
• Auto-processing options

🔧 Configuration

The scan_config.ini file allows you to customize:

[SCAN]
output_dir = Scans
file_format = jpg
quality = medium
auto_crop = true
deskew = true
color_mode = 1
combine_pdf = false

Quality Settings

• Low: 150 DPI (fast, smaller files)
• Medium: 300 DPI (balanced)
• High: 600 DPI (high quality, larger files)

Supported Formats

• JPG: Compressed, good for documents
• PNG: Lossless, good for images
• TIFF: High quality, large files
• PDF: Portable document format

📁 Project Structure

pyautoscan/
├── 📁 pyautoscan/           # Main package
│   ├── __init__.py          # Package initialization
│   ├── basic_scan.py        # Basic scanning functionality
│   ├── advanced_scan.py     # Advanced scanning features
│   └── scanner_info.py      # Scanner information utility
├── 📁 tests/                # Test suite
│   ├── __init__.py
│   └── test_basic_scan.py
├── 📁 .github/              # GitHub Actions workflows
├── 📁 Scans/                # Output directory (gitignored)
├── 📄 README.md             # Main documentation
├── 📄 DEVELOPMENT.md        # Development guide
├── 📄 TESTING.md            # Testing documentation
├── 📄 CHANGELOG.md          # Version history
├── 📄 LICENSE               # MIT License
├── 📄 requirements.txt      # Production dependencies
├── 📄 requirements-dev.txt  # Development dependencies
├── 📄 pyproject.toml       # Modern Python packaging
├── 📄 setup.py             # Traditional packaging
├── 📄 MANIFEST.in          # Package file inclusion
├── 📄 .gitignore           # Git ignore rules
├── �� .pre-commit-config.yaml  # Code quality hooks
├── 📄 Makefile             # Development commands
├── 📄 run_scanner.bat      # Windows launcher
└── 📄 scan_config.ini      # Configuration file

🔧 Development

Repository

• GitHub: https://github.com/Pandiyarajk/pyautoscan
• Issues: https://github.com/Pandiyarajk/pyautoscan/issues
• Releases: https://github.com/Pandiyarajk/pyautoscan/releases

Build Status

The project uses GitHub Actions for continuous integration:

• Build: Windows executables for Python 3.8-3.13
• Test: Automated testing on Windows with Python 3.13
• Release: Automatic builds on releases

🚀 Building Executables

Using PyInstaller

# Install PyInstaller
pip install pyinstaller

# Build basic scanner
pyinstaller --onefile --windowed pyautoscan/basic_scan.py

# Build advanced scanner
pyinstaller --onefile --windowed pyautoscan/advanced_scan.py

Note: Successfully tested with Python 3.13 and HP Printer scanner features.

Using GitHub Actions

The repository includes a GitHub Actions workflow that automatically builds Windows executables on each release.

🔍 Troubleshooting

Common Issues

1. "No scanner detected"

   • Ensure scanner is connected and powered on
   • Verify WIA drivers are installed
   • Run scanner_info.py to test connection

2. Permission errors

   • Run as administrator if needed
   • Check Windows security settings

3. Format not supported

   • Verify scanner supports requested format
   • Check scanner_info.py output for supported formats

Scanner Compatibility

This tool works with any scanner that supports Windows WIA (Windows Image Acquisition). Most modern scanners are compatible.

Tested Hardware:

• HP Printer scanner features (confirmed working)
• Windows WIA drivers
• Python 3.13 compatibility verified

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Repository: https://github.com/Pandiyarajk/pyautoscan

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Pandiyaraj Karuppasamy
Email: pandiyarajk@live.com
Date: 27-Aug-2025

🙏 Acknowledgments

• Windows WIA (Windows Image Acquisition) API
• Python Imaging Library (PIL/Pillow)
• pywin32 for Windows COM integration
• PowerLogger for enhanced logging capabilities

📞 Support

If you encounter any issues or have questions:

• Open an issue on GitHub
• Check the troubleshooting section above
• Verify your scanner compatibility

---

Note: This tool is designed specifically for Windows systems and requires a compatible scanner with WIA drivers.