{"id":28719260,"url":"https://github.com/theseraphim/naps2-cli-wrapper","last_synced_at":"2026-05-10T05:39:08.779Z","repository":{"id":297241944,"uuid":"996146596","full_name":"TheSeraphim/naps2-cli-wrapper","owner":"TheSeraphim","description":"Scanner automation scripts in C# (.NET 8) and Python - CLI wrappers for NAPS2 with auto-detection, named parameters, and multi-format output","archived":false,"fork":false,"pushed_at":"2025-06-04T15:37:03.000Z","size":303,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-15T06:01:54.890Z","etag":null,"topics":["automation","batch-processing","cli","cross-platform","document-scanning","dotnet","naps2","python","scanner","scripts"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TheSeraphim.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-04T14:19:17.000Z","updated_at":"2025-06-04T15:37:05.000Z","dependencies_parsed_at":"2025-06-04T21:11:17.858Z","dependency_job_id":"a3e71a7f-5d4d-441b-be7d-44f9bfe2e940","html_url":"https://github.com/TheSeraphim/naps2-cli-wrapper","commit_stats":null,"previous_names":["theseraphim/naps2-cli-wrapper"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TheSeraphim/naps2-cli-wrapper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheSeraphim%2Fnaps2-cli-wrapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheSeraphim%2Fnaps2-cli-wrapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheSeraphim%2Fnaps2-cli-wrapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheSeraphim%2Fnaps2-cli-wrapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheSeraphim","download_url":"https://codeload.github.com/TheSeraphim/naps2-cli-wrapper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheSeraphim%2Fnaps2-cli-wrapper/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259929968,"owners_count":22933528,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","batch-processing","cli","cross-platform","document-scanning","dotnet","naps2","python","scanner","scripts"],"created_at":"2025-06-15T06:00:57.454Z","updated_at":"2026-05-10T05:39:08.751Z","avatar_url":"https://github.com/TheSeraphim.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](./scanner-logo.png)\n\n\n# Scanner Automation Scripts\n\nScanner automation scripts in C# (.NET 8) and Python - CLI wrappers for NAPS2 with auto-detection, named parameters, and multi-format output.\n\n## What it does\n\nThese scripts provide a streamlined command-line interface for document scanning using NAPS2 as the backend. Both scripts offer identical functionality: automatic scanner detection, support for WIA and TWAIN drivers, and can save scans in multiple formats (PNG, JPEG, TIFF, BMP, PDF) with customizable resolution and color settings.\n\n### Key Features\n\n- ✅ **Two implementations** - C# (.NET 8) and Python 3.7+\n- ✅ **Identical functionality** - Same parameters and behavior\n- ✅ **Automatic scanner detection** - No need to remember device names\n- ✅ **Multiple output formats** - PNG, JPEG, TIFF, BMP, PDF\n- ✅ **Flexible DPI settings** - From 75 to 1200+ DPI\n- ✅ **Color mode options** - Color, grayscale, black \u0026 white\n- ✅ **ADF and flatbed support** - Works with document feeders and glass beds\n- ✅ **Batch scanning** - Multiple pages automatically numbered\n- ✅ **Cross-platform** - Both scripts work on Windows, macOS, and Linux\n\n## Files in this Repository\n\n- **`scanner.cs`** - C# (.NET 8) implementation\n- **`scanner.py`** - Python implementation (identical functionality)\n- **`README.md`** - This documentation\n\n## Prerequisites\n\n### Common Requirements\n\n#### NAPS2 Scanner Software\nDownload and install NAPS2 from:\n- **Official website**: https://www.naps2.com/download\n- **Recommended version**: 8.1.4 or newer\n\n**Installation Steps:**\n1. Download `naps2-8.1.4-win-x64.exe` (or appropriate version for your OS)\n2. Run the installer with default settings\n3. **Important**: Make sure NAPS2 is added to your system PATH\n\n**Verify NAPS2 installation:**\n```bash\nNAPS2.Console --version\n# Should show version information\n```\n\n#### Scanner Drivers\nEnsure your scanner has proper drivers installed:\n- **WIA drivers** (Windows Image Acquisition) - Usually installed automatically\n- **TWAIN drivers** (optional) - Often more reliable for business scanners\n\n### For C# Script (scanner.cs)\n\n#### .NET 8 Runtime\nDownload and install from: https://dotnet.microsoft.com/download/dotnet/8.0\n\n**Verify installation:**\n```bash\ndotnet --version\n# Should show 8.0.x or higher\n```\n\n### For Python Script (scanner.py)\n\n#### Python 3.7+\nDownload from: https://www.python.org/downloads/\n\n**Verify installation:**\n```bash\npython --version\n# Should show 3.7.x or higher\n```\n\n**No additional packages required** - uses only Python standard library.\n\n## Usage\n\nBoth scripts have identical command-line interfaces:\n\n### Basic Syntax\n```bash\n# C# version\ndotnet run scanner.cs [options]\n\n# Python version  \npython scanner.py [options]\n```\n\n### Command Line Options\n\n| Option | Short | Description | Default |\n|--------|-------|-------------|---------|\n| `--output \u003cfolder\u003e` | `-o` | Output folder path | `scanned_pages` |\n| `--prefix \u003cname\u003e` | `-p` | File name prefix | `page` |\n| `--format \u003cext\u003e` | `-f` | Output format (png, jpg, tiff, bmp, pdf) | `png` |\n| `--dpi \u003cnumber\u003e` | `-d` | Scanning resolution | `300` |\n| `--color \u003cmode\u003e` | `-c` | Color mode (color, gray, bw) | `color` |\n| `--source \u003csrc\u003e` | `-s` | Paper source (feeder, glass) | `feeder` |\n| `--device \u003cname\u003e` | | Specific scanner device name | auto-detect |\n| `--driver \u003ctype\u003e` | | Scanner driver (wia, twain) | `wia` |\n| `--help` | `-h` | Show help information | |\n\n## Examples\n\nAll examples work identically with both scripts (just change the command):\n\n### Basic Examples\n\n**Simple scan with defaults:**\n```bash\n# C# version\ndotnet run scanner.cs\n\n# Python version\npython scanner.py\n\n# Output: scanned_pages/page_0001.png (300 DPI, color, ADF)\n```\n\n**Show help:**\n```bash\npython scanner.py --help\ndotnet run scanner.cs --help\n```\n\n### Custom Output Examples\n\n**Scan to specific folder:**\n```bash\npython scanner.py --output \"D:\\Documents\\Scans\"\n# Output: D:\\Documents\\Scans\\page_0001.png\n```\n\n**Custom file prefix and format:**\n```bash\npython scanner.py --prefix \"invoice\" --format jpg --output \"C:\\Invoices\"\n# Output: C:\\Invoices\\invoice_0001.jpg, invoice_0002.jpg, etc.\n```\n\n### Quality and Format Examples\n\n**High-resolution scanning:**\n```bash\npython scanner.py --dpi 600 --format tiff --prefix \"document_hq\"\n# Output: scanned_pages/document_hq_0001.tiff (600 DPI color TIFF)\n```\n\n**Web-optimized scanning:**\n```bash\npython scanner.py --dpi 150 --format jpg --color gray --prefix \"web\"\n# Output: scanned_pages/web_0001.jpg (150 DPI grayscale JPEG)\n```\n\n**PDF multi-page document:**\n```bash\npython scanner.py --format pdf --prefix \"contract\" --color bw\n# Output: scanned_pages/contract.pdf (all pages in one PDF)\n```\n\n### Driver and Device Examples\n\n**Specific scanner device:**\n```bash\npython scanner.py --device \"Xerox WIA - ETE84DEC0F2B58\" --source feeder\n```\n\n**Use TWAIN driver:**\n```bash\npython scanner.py --driver twain --format pdf --prefix \"report\"\n```\n\n**Flatbed scanning:**\n```bash\npython scanner.py --source glass --dpi 600 --format png --prefix \"photo\"\n```\n\n### Workflow Examples\n\n**Daily document scanning:**\n```bash\n# Windows\npython scanner.py --prefix \"daily_%DATE%\" --format pdf\n\n# Linux/macOS  \npython scanner.py --prefix \"daily_$(date +%Y%m%d)\" --format pdf\n```\n\n**Invoice processing:**\n```bash\npython scanner.py --output \"C:\\Accounting\\Invoices\" --prefix \"inv\" --format jpg --color gray --dpi 300\n```\n\n**Legal document archiving:**\n```bash\npython scanner.py --output \"D:\\Legal\\Cases\\2024\" --prefix \"case_001\" --format tiff --dpi 600 --color gray\n```\n\n## Running the Scripts\n\n### C# Script\n```bash\n# Option 1: Direct execution with dotnet\ndotnet run scanner.cs --output \"D:\\scans\" --format jpg\n\n# Option 2: Compile first, then run\ndotnet build scanner.cs\n./scanner --dpi 600 --color gray\n```\n\n### Python Script\n```bash\n# Direct execution\npython scanner.py --output \"D:\\scans\" --format jpg\n\n# Make executable (Linux/macOS)\nchmod +x scanner.py\n./scanner.py --dpi 600 --color gray\n```\n\n## Troubleshooting\n\n### Scanner Not Found\n```bash\n# List available scanners\nNAPS2.Console --driver wia --listdevices\nNAPS2.Console --driver twain --listdevices\n\n# Try different driver\npython scanner.py --driver twain\n```\n\n### NAPS2 Not Found Error\n1. Verify NAPS2 installation: `NAPS2.Console --version`\n2. Add NAPS2 to PATH environment variable\n3. Reinstall NAPS2 with default settings\n\n### Script-Specific Issues\n\n**C# Script:**\n- Ensure .NET 8 runtime is installed\n- Check that `dotnet` command is available in PATH\n\n**Python Script:**\n- Ensure Python 3.7+ is installed\n- Check that `python` command works in terminal\n\n### Scanner Issues\n\n**ADF/Feeder Problems:**\n```bash\n# Try flatbed instead\npython scanner.py --source glass\n\n# Try TWAIN driver for better ADF support\npython scanner.py --driver twain --source feeder\n```\n\n**Poor Scan Quality:**\n```bash\n# Increase DPI\npython scanner.py --dpi 600\n\n# Use uncompressed format\npython scanner.py --format tiff\n```\n\n## Output Formats\n\n- **PNG** - Best quality, lossless compression, moderate file size\n- **JPEG** - Good quality, lossy compression, smallest file size  \n- **TIFF** - Professional quality, optional compression, large file size\n- **BMP** - Uncompressed, largest file size, maximum quality\n- **PDF** - Multi-page document format, good for archiving\n\n## DPI Recommendations\n\n- **75-150 DPI** - Web use, email attachments\n- **300 DPI** - Standard document scanning, printing\n- **600 DPI** - High quality documents, small text\n- **1200+ DPI** - Professional archival, photography\n\n## Technical Notes\n\n### C# Script Features\n- **Modern .NET 8** - Top-level statements, async/await, nullable reference types\n- **Fast startup** - Optimized for performance\n- **Cross-platform** - Runs on Windows, macOS, Linux\n\n### Python Script Features  \n- **Python 3.7+** - Uses modern asyncio features\n- **Standard library only** - No external dependencies\n- **Cross-platform** - Works anywhere Python runs\n\n### Both Scripts\n- **Identical behavior** - Same parameters, same output, same error handling\n- **Async operations** - Non-blocking I/O for better performance\n- **Automatic file detection** - Verifies scan success by checking created files\n- **Real-time output** - Shows NAPS2 progress during scanning\n\n## Contributing\n\n1. Fork the repository\n2. Make your changes to the scripts\n3. Test with your scanner setup\n4. Submit a pull request\n\nBoth scripts should maintain identical functionality when changes are made.\n\n## License\n\nThis project is licensed under the MIT License.\n\n## Support\n\n- **Issues**: Report bugs and feature requests on GitHub\n- **NAPS2 Support**: Visit https://www.naps2.com for NAPS2-specific issues\n- **Scanner Drivers**: Contact your scanner manufacturer for driver support\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheseraphim%2Fnaps2-cli-wrapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheseraphim%2Fnaps2-cli-wrapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheseraphim%2Fnaps2-cli-wrapper/lists"}