{"id":43307120,"url":"https://github.com/tripledoublev/handwritten-spreadsheets","last_synced_at":"2026-02-01T20:42:15.712Z","repository":{"id":321126037,"uuid":"1053048355","full_name":"tripledoublev/handwritten-spreadsheets","owner":"tripledoublev","description":"Convert handwritten notes to structured CSV using AI","archived":false,"fork":false,"pushed_at":"2025-10-27T22:30:34.000Z","size":44,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-28T00:16:11.756Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://handwritten-spreadsheets.vercel.app","language":"HTML","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/tripledoublev.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-08T23:21:45.000Z","updated_at":"2025-10-27T22:30:34.000Z","dependencies_parsed_at":"2025-10-28T00:16:14.034Z","dependency_job_id":"4d3c8e15-ed1e-4dd0-912c-366ab926c2fc","html_url":"https://github.com/tripledoublev/handwritten-spreadsheets","commit_stats":null,"previous_names":["tripledoublev/handwritten-spreadsheets"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tripledoublev/handwritten-spreadsheets","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tripledoublev%2Fhandwritten-spreadsheets","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tripledoublev%2Fhandwritten-spreadsheets/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tripledoublev%2Fhandwritten-spreadsheets/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tripledoublev%2Fhandwritten-spreadsheets/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tripledoublev","download_url":"https://codeload.github.com/tripledoublev/handwritten-spreadsheets/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tripledoublev%2Fhandwritten-spreadsheets/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28990113,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T20:36:14.625Z","status":"ssl_error","status_checked_at":"2026-02-01T20:36:11.271Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2026-02-01T20:42:14.798Z","updated_at":"2026-02-01T20:42:15.707Z","avatar_url":"https://github.com/tripledoublev.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Handwritten Spreadsheet to CSV\n\nConvert handwritten spreadsheet images to structured CSV data using AI vision models.\n\n## What it does?\n\n- **Image Upload**: Support for various image formats (PNG, JPG, etc.)\n- **AI-Powered Extraction**: Uses Ollama vision models for accurate text recognition\n- **Model Selection**: Choose from available Ollama models for optimal performance\n- **Confidence Scoring**: Get confidence scores for each extracted cell to identify uncertain data\n- **Auto-Detect Headers**: Automatically detect column headers from the image\n- **Custom Column Mapping**: Define your own spreadsheet headers when needed\n- **Optional Instructions**: Provide additional context for better extraction\n- **Live Preview**: See extracted data with confidence highlighting before saving\n- **CSV Export**: Save and download results as CSV files\n- **Ollama Integration**: Built-in status checking and custom endpoint configuration\n\n## Quick Start\n\n### Prerequisites\n\n1. **Python 3.7+** (for local setup)\n2. **Docker \u0026 Docker Compose** (for Docker setup)\n3. **Ollama** with a vision model\n   - [Download Ollama](https://ollama.com/download)\n   - Install a vision model: `ollama pull qwen2.5vl:7b` (recommended) or `ollama pull llama3.2-vision`\n\n## Setup Options\n\n### Option 1: Local Development Setup\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/tripledoublev/handwritten-spreadsheets.git\n   cd handwritten-spreadsheets\n   ```\n\n2. **Install dependencies**\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n3. **Start Ollama** (if not already running)\n   ```bash\n   ollama serve\n   ```\n\n4. **Run the application**\n   ```bash\n   python app.py\n   ```\n\n5. **Open your browser** to `http://127.0.0.1:5000`\n\n### Option 2: Docker Setup\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/tripledoublev/handwritten-spreadsheets.git\n   cd handwritten-spreadsheets\n   ```\n\n2. **Configure environment** (optional)\n   ```bash\n   cp env.example .env\n   # Edit .env file to customize Ollama settings if needed\n   ```\n\n3. **Start the application**\n   ```bash\n   docker compose up --build -d\n   ```\n\n4. **Download the vision model** (first time only)\n   ```bash\n   # This downloads the llama3.2-vision model (~7.8 GB)\n   docker exec -it handwritten-spreadsheets-app-1 ollama pull llama3.2-vision\n   ```\n\n5. **Open your browser** to `http://127.0.0.1:5000`\n\n6. **Stop the application**\n   ```bash\n   docker compose down\n   ```\n\n#### Docker Benefits\n- **Isolated Environment**: No need to install Python dependencies locally\n- **Consistent Setup**: Same environment across different machines\n- **Easy Cleanup**: Remove containers to clean up completely\n- **Production Ready**: Same setup used in production deployments\n\n## Usage\n\n1. **Check Ollama Status**: The app will automatically detect if Ollama is running\n2. **Select Model**: Choose from available Ollama models (defaults to qwen2.5vl:7b)\n3. **Upload Image**: Select a photo of your handwritten spreadsheet\n4. **Define Headers** (optional): Enter column names separated by commas (e.g., \"name,email,phone,notes\")\n   - **Auto-detect mode**: Leave empty to automatically detect headers from the image\n   - **Specify mode**: Enter column names to force specific headers\n5. **Set Confidence Threshold**: Adjust the threshold for highlighting uncertain data (default: 0.7)\n6. **Add Instructions** (optional): Provide specific guidance for extraction\n7. **Extract Data**: Click \"Extract Data\" to process the image\n8. **Preview Results**: Review the extracted data with confidence scores and highlighting\n9. **Save to CSV**: Click \"Save Rows to CSV\" to append data to your CSV file\n10. **Download**: Use \"Download CSV\" to get your complete dataset\n\n## Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the project root to configure external Ollama endpoints:\n\n```bash\n# Ollama server configuration\nOLLAMA_HOST=http://localhost:11434\nOLLAMA_USERNAME=your_username\nOLLAMA_PASSWORD=your_password\nOLLAMA_MODEL=qwen2.5vl:7b\n```\n\n### Custom Ollama Endpoint\n\nIf Ollama is running on a different host/port:\n1. The status indicator will show \"offline\" for localhost:11434\n2. Click to reveal the custom endpoint configuration\n3. Enter your Ollama URL (e.g., `http://192.168.1.123:11434`)\n4. Click \"Test Connection\" to verify\n\n### Model Selection\n\n- **Default Model**: The app uses `qwen2.5vl:7b` by default (configurable via `OLLAMA_MODEL`)\n- **Model Dropdown**: Select from available models in the web interface\n- **Model Information**: Each model shows its size and current status\n- **Performance**: Different models may have varying accuracy and speed\n\n### File Structure\n\n```\nhandwritten-spreadsheets/\n├── app.py                 # Flask backend\n├── requirements.txt       # Python dependencies\n├── Dockerfile            # Docker container configuration\n├── docker-compose.yaml   # Docker Compose configuration\n├── env.example           # Environment variables template\n├── templates/\n│   └── index.html        # Web interface\n├── data/\n│   └── results.csv       # Output CSV file (auto-created)\n├── archive/\n│   └── photo-to-csv.py   # Original script\n└── ollama/               # Ollama model files (Docker setup)\n```\n\n## API Endpoints\n\n- `GET /` - Serve web interface\n- `GET /ollama-status` - Check Ollama connectivity\n- `GET /ollama-models` - Get list of available Ollama models\n- `POST /extract` - Process image and extract data with confidence scores\n- `POST /save` - Save extracted data to CSV\n- `GET /download` - Download current CSV file\n\n## Tips for Best Results\n\n- **Image Quality**: Use high-resolution, well-lit photos\n- **Clear Handwriting**: Ensure text is legible\n- **Consistent Format**: Maintain regular spacing and alignment\n- **Column Headers**: Be specific with column names for better mapping\n- **Additional Instructions**: Mention any special formatting or context\n- **Model Selection**: Try different models to find the best performance for your handwriting style\n- **Confidence Scores**: Review highlighted cells (low confidence) and verify accuracy\n- **Confidence Threshold**: Adjust the threshold (0.7 default) to highlight more or fewer uncertain cells\n- **Auto-detect vs Specify**: Use auto-detect for well-structured tables, specify headers for complex layouts\n\n## Troubleshooting\n\n### Ollama Connection Issues\n- Ensure Ollama is installed and running (`ollama serve`)\n- Check if a vision model is available (`ollama list`)\n- Verify firewall settings if using remote Ollama instance\n- Check environment variables in `.env` file for custom endpoints\n\n### Extraction Problems\n- Try providing more specific column headers\n- Add instructions about handwriting style or format\n- Ensure image is clear and well-lit\n- Check that all text is visible in the uploaded image\n- Try different models for better accuracy\n- Review confidence scores to identify problematic areas\n- Use auto-detect mode for well-structured tables\n\n### CSV Output Issues\n- Check the `data/` directory for the results.csv file\n- Ensure write permissions in the project directory\n\n### Docker Issues\n- **Container won't start**: Check Docker is running and ports 5000 is available\n- **Model download fails**: Ensure sufficient disk space (~8GB for llama3.2-vision)\n- **Permission errors**: On Linux, you may need to run `sudo docker compose up`\n- **Port conflicts**: Change the port mapping in docker-compose.yaml if 5000 is in use\n- **Environment variables**: Ensure .env file exists and has correct Ollama settings\n- **Container logs**: Use `docker compose logs` to debug issues\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test it\n5. Submit a pull request\n\n## License\n\nThis project is open source. Feel free to use and modify as needed.\n\n## Acknowledgments\n\n- Built with [Flask](https://flask.palletsprojects.com/)\n- Powered by [Ollama](https://ollama.com/) and [llama3.2-vision](https://ollama.com/library/llama3.2-vision)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftripledoublev%2Fhandwritten-spreadsheets","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftripledoublev%2Fhandwritten-spreadsheets","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftripledoublev%2Fhandwritten-spreadsheets/lists"}