{"id":28546234,"url":"https://github.com/raykavin/platerecon","last_synced_at":"2025-07-07T06:31:40.101Z","repository":{"id":297126512,"uuid":"994732264","full_name":"raykavin/platerecon","owner":"raykavin","description":"A real-time license plate recognition system built in Go using OpenCV (GoCV) and Tesseract OCR. This system captures video from a camera, detects Brazilian license plates, and verifies them against an authorized list for access control.","archived":false,"fork":false,"pushed_at":"2025-06-04T01:23:07.000Z","size":178,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"develop","last_synced_at":"2025-06-04T07:56:24.195Z","etag":null,"topics":["camera","gocv","golang","gosseract","ip-camera","license-plate-recognition","opencv","real-time","tesseract-ocr"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raykavin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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-02T11:55:00.000Z","updated_at":"2025-06-04T01:23:10.000Z","dependencies_parsed_at":"2025-06-04T07:56:34.025Z","dependency_job_id":"39914b77-a119-4e79-af82-2b05d2f61c7e","html_url":"https://github.com/raykavin/platerecon","commit_stats":null,"previous_names":["raykavin/platerecon"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/raykavin/platerecon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raykavin%2Fplaterecon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raykavin%2Fplaterecon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raykavin%2Fplaterecon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raykavin%2Fplaterecon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raykavin","download_url":"https://codeload.github.com/raykavin/platerecon/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raykavin%2Fplaterecon/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264027592,"owners_count":23546103,"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":["camera","gocv","golang","gosseract","ip-camera","license-plate-recognition","opencv","real-time","tesseract-ocr"],"created_at":"2025-06-09T23:09:07.456Z","updated_at":"2025-07-07T06:31:40.094Z","avatar_url":"https://github.com/raykavin.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# License Plate Recognition System\r\n\r\nA real-time license plate recognition system built in Go using OpenCV (GoCV) and Tesseract OCR. This system captures video from a camera, detects Brazilian license plates, and verifies them against an authorized list for access control.\r\n\r\n![Preview of Platerecon 1](images/1.jpg)\r\n\r\n\r\n## Features\r\n\r\n- **Real-time Detection**: Live camera feed processing for license plate recognition\r\n- **Brazilian Plate Support**: Supports both old format (ABC1234) and Mercosul format (ABC1D23) plates\r\n- **OCR Integration**: Uses Tesseract OCR with fallback to simple pattern recognition\r\n- **Access Control**: Maintains a whitelist of authorized license plates\r\n- **Debug Mode**: Visual debugging with bounding boxes and confidence scores\r\n- **Robust Processing**: Advanced image preprocessing for better OCR accuracy\r\n\r\n## Prerequisites\r\n\r\n### Dependencies\r\n\r\n- **Go** (1.19 or higher)\r\n- **OpenCV** (4.x)\r\n- **Tesseract OCR** (optional but recommended)\r\n- **GoCV** - Go bindings for OpenCV\r\n- **gosseract** - Go bindings for Tesseract\r\n\r\n### System Requirements\r\n\r\n- Camera (webcam or USB camera)\r\n- Linux, macOS, or Windows\r\n- Minimum 4GB RAM recommended\r\n\r\n## Installation\r\n\r\n### Option 1: Using DevContainer (Recommended) 🐳\r\n\r\nThe easiest way to run this project is using the provided DevContainer configuration. The system has been tested on **Debian 12** with camera passthrough to the container.\r\n\r\n#### Prerequisites:\r\n- Docker\r\n- VS Code with Dev Containers extension\r\n- Camera connected to host system (`/dev/video0`)\r\n\r\n#### Setup:\r\n1. Clone the repository:\r\n```bash\r\ngit clone https://github.com/raykavin/platerecon\r\ncd platerecon\r\n```\r\n\r\n2. Open in VS Code and select \"Reopen in Container\" when prompted, or:\r\n```bash\r\ncode .\r\n# Then: Ctrl+Shift+P -\u003e \"Dev Containers: Reopen in Container\"\r\n```\r\n\r\n3. The container will automatically:\r\n   - Install Go 1.24\r\n   - Install OpenCV and GoCV\r\n   - Install Tesseract OCR\r\n   - Configure Fish shell\r\n   - Mount your camera device\r\n   - Set up the development environment\r\n\r\n4. Build and run:\r\n```bash\r\ngo mod tidy\r\ngo build -o plate-recognition main.go\r\n./plate-recognition\r\n```\r\n\r\n#### DevContainer Features:\r\n- **Pre-configured Environment**: All dependencies installed automatically\r\n- **Camera Support**: Direct access to host camera via device passthrough\r\n- **Display Support**: X11/Wayland forwarding for GUI applications\r\n- **Fish Shell**: Enhanced terminal experience with autocomplete\r\n- **VS Code Integration**: Go extensions and debugging support\r\n- **Tested Environment**: Verified on Debian 12 host systems\r\n\r\n#### DevContainer Configuration:\r\n\r\n**Dockerfile:**\r\n```dockerfile\r\n# Base image\r\nFROM mcr.microsoft.com/devcontainers/go:1-1.24-bookworm\r\n\r\nENV DEBIAN_FRONTEND=noninteractive\r\nARG USERNAME=vscode\r\n\r\n# Install packages\r\nRUN apt-get update \u0026\u0026 apt-get install -y --no-install-recommends \\\r\n    fish \\\r\n    git \\\r\n    curl \\\r\n    sudo \\\r\n    libtesseract-dev \\\r\n    libleptonica-dev \\\r\n    tesseract-ocr \\\r\n    \u0026\u0026 apt-get clean \u0026\u0026 rm -rf /var/lib/apt/lists/*\r\n\r\n# Change shell to fish\r\nRUN chsh -s /usr/bin/fish ${USERNAME}\r\n\r\n# Use non-root user\r\nUSER ${USERNAME}\r\nWORKDIR /home/${USERNAME}/workspaces/platerecon\r\n\r\n# Clone and install GoCV\r\nRUN git clone https://github.com/hybridgroup/gocv.git /tmp/gocv \\\r\n    \u0026\u0026 cd /tmp/gocv \\\r\n    \u0026\u0026 git checkout v0.41.0 \\\r\n    \u0026\u0026 make install \\\r\n    \u0026\u0026 rm -rf /tmp/gocv\r\n\r\n# Start in fish shell\r\nCMD [\"fish\"]\r\n```\r\n\r\n**devcontainer.json:**\r\n```json\r\n{\r\n    \"name\": \"Go DevContainer with Fish\",\r\n    \"remoteUser\": \"vscode\",\r\n    \"build\": {\r\n        \"dockerfile\": \"Dockerfile\",\r\n        \"context\": \"..\"\r\n    },\r\n    \"workspaceFolder\": \"/workspaces/platerecon\",\r\n    \"forwardPorts\": [3000],\r\n    \"runArgs\": [\r\n        \"--network=host\",\r\n        \"--device=/dev/video0\",\r\n        \"--group-add=video\"\r\n    ],\r\n    \"containerEnv\": {\r\n        \"DISPLAY\": \"${env:DISPLAY}\",\r\n        \"WAYLAND_DISPLAY\": \"${env:WAYLAND_DISPLAY}\",\r\n        \"XDG_RUNTIME_DIR\": \"${env:XDG_RUNTIME_DIR}\"\r\n    },\r\n    \"mounts\": [\r\n        \"source=/run/user/1000/wayland-0,target=/run/user/1000/wayland-0,type=bind\",\r\n        \"source=${env:XDG_RUNTIME_DIR},target=${env:XDG_RUNTIME_DIR},type=bind\"\r\n    ],\r\n    \"postCreateCommand\": \"go mod tidy \u0026\u0026 git config --global --add safe.directory /workspaces/platerecon\",\r\n    \"features\": {\r\n        \"ghcr.io/devcontainers/features/git:1\": {}\r\n    },\r\n    \"customizations\": {\r\n        \"vscode\": {\r\n            \"extensions\": [\r\n                \"golang.Go\",\r\n                \"golang.go-nightly\",\r\n                \"liuchao.go-struct-tag\",\r\n                \"yokoe.vscode-postfix-go\",\r\n                \"ms-ceintl.vscode-language-pack-pt-br\",\r\n                \"streetsidesoftware.code-spell-checker\",\r\n                \"streetsidesoftware.code-spell-checker-portuguese-brazilian\",\r\n                \"visualstudioexptteam.vscodeintellicode\",\r\n                \"redhat.vscode-yaml\",\r\n                \"teddyandturtle.fish\"\r\n            ],\r\n            \"settings\": {\r\n                \"terminal.integrated.defaultProfile.linux\": \"fish\",\r\n                \"go.toolsManagement.checkForUpdates\": \"local\",\r\n                \"go.useLanguageServer\": true,\r\n                \"go.gopath\": \"/go\",\r\n                \"go.goroot\": \"/usr/local/go\"\r\n            }\r\n        }\r\n    }\r\n}\r\n```\r\n\r\n### Option 2: Manual Installation\r\n\r\n#### Ubuntu/Debian:\r\n```bash\r\nsudo apt update\r\nsudo apt install libopencv-dev pkg-config\r\n```\r\n\r\n#### macOS (using Homebrew):\r\n```bash\r\nbrew install opencv pkg-config\r\n```\r\n\r\n#### Windows:\r\nFollow the [OpenCV installation guide](https://docs.opencv.org/master/d3/d52/tutorial_windows_install.html)\r\n\r\n#### Install Tesseract OCR (Optional)\r\n\r\n**Ubuntu/Debian:**\r\n```bash\r\nsudo apt install tesseract-ocr libtesseract-dev\r\n```\r\n\r\n**macOS:**\r\n```bash\r\nbrew install tesseract\r\n```\r\n\r\n**Windows:**\r\nDownload from [GitHub Tesseract releases](https://github.com/UB-Mannheim/tesseract/wiki)\r\n\r\n#### Install Go Dependencies\r\n\r\n```bash\r\ngo mod init license-plate-recognition\r\ngo get gocv.io/x/gocv\r\ngo get github.com/otiai10/gosseract/v2\r\n```\r\n\r\n#### Build the Application\r\n\r\n```bash\r\ngo build -o plate-recognition main.go\r\n```\r\n\r\n## Usage\r\n\r\n### Basic Usage\r\n\r\n```bash\r\n./plate-recognition\r\n```\r\n\r\n### Controls\r\n\r\n- **'q' or ESC**: Quit the application\r\n- **'d'**: Toggle debug mode (shows detection bounding boxes)\r\n\r\n### Configuration\r\n\r\nThe system can be configured by modifying the following parameters in the code:\r\n\r\n```go\r\n// Authorized plates list\r\nallowedPlates: []string{\"QFQ4H64\", \"ABC1234\", \"BRA2E19\"}\r\n\r\n// Detection parameters\r\nminConfidence: 30.0        // Minimum OCR confidence threshold\r\nminTextSize: 6            // Minimum text length\r\nwaitTime: 1 * time.Second // Time between detections\r\n\r\n// Plate geometry constraints\r\nminPlateArea: 5000         // Minimum plate area in pixels\r\nmaxPlateArea: 50000        // Maximum plate area in pixels\r\nminAspectRatio: 2.0        // Minimum width/height ratio\r\nmaxAspectRatio: 5.5        // Maximum width/height ratio\r\n```\r\n\r\n## System Architecture\r\n\r\n### Core Components\r\n\r\n1. **PlateRecognitionSystem**: Main system controller\r\n2. **PlateDetection**: Represents a detected license plate with confidence\r\n3. **PlateCandidate**: Represents a potential plate region before OCR\r\n\r\n### Detection Pipeline\r\n\r\n1. **Image Preprocessing**: \r\n   - Grayscale conversion\r\n   - Bilateral filtering for noise reduction\r\n   - Canny edge detection\r\n\r\n2. **Region Detection**:\r\n   - Contour analysis\r\n   - Geometric filtering based on aspect ratio and area\r\n   - Confidence scoring\r\n\r\n3. **OCR Processing**:\r\n   - ROI extraction and enhancement\r\n   - Tesseract OCR with custom configuration\r\n   - Text normalization and validation\r\n\r\n4. **Plate Validation**:\r\n   - Format verification (Brazilian patterns)\r\n   - Authorization check\r\n   - Access control decision\r\n\r\n### Supported Plate Formats\r\n\r\n- **Old Brazilian Format**: ABC1234 (3 letters + 4 numbers)\r\n- **Mercosul Format**: ABC1D23 (3 letters + 1 number + 1 letter + 2 numbers)\r\n\r\n## Performance Optimization\r\n\r\n### Camera Settings\r\n\r\nThe system automatically configures the camera for optimal performance:\r\n- Resolution: 1280x720\r\n- Frame rate: 30 FPS\r\n- Auto-exposure adjustment\r\n\r\n### OCR Optimization\r\n\r\n- Custom Tesseract configuration for license plates\r\n- Character whitelist: A-Z, 0-9\r\n- Single-line page segmentation mode\r\n- Morphological operations for text enhancement\r\n\r\n## Troubleshooting\r\n\r\n### Common Issues\r\n\r\n1. **Camera not detected**:\r\n   - Check camera connection\r\n   - Verify camera permissions\r\n   - Try different camera index (modify `gocv.OpenVideoCapture(0)`)\r\n\r\n2. **Tesseract not found**:\r\n   - System falls back to simple pattern recognition\r\n   - Install Tesseract OCR for better accuracy\r\n\r\n3. **Low detection accuracy**:\r\n   - Improve lighting conditions\r\n   - Adjust `minConfidence` threshold\r\n   - Clean camera lens\r\n\r\n### Debug Mode\r\n\r\nEnable debug mode by pressing 'd' to see:\r\n- Detection bounding boxes\r\n- Confidence scores\r\n- Processing parameters\r\n\r\n## API Reference\r\n\r\n### Main Functions\r\n\r\n#### `NewPlateRecognitionSystem() *PlateRecognitionSystem`\r\nCreates a new instance of the recognition system with default parameters.\r\n\r\n#### `Initialize() error`\r\nInitializes camera, windows, and OCR components.\r\n\r\n#### `Run() error`\r\nStarts the main processing loop.\r\n\r\n#### `Cleanup()`\r\nReleases all system resources.\r\n\r\n### Key Methods\r\n\r\n#### `detectPlates(img gocv.Mat) []PlateDetection`\r\nDetects and recognizes license plates in the given image.\r\n\r\n#### `verifyPlate(img gocv.Mat) (bool, string)`\r\nVerifies if any detected plate is authorized for access.\r\n\r\n#### `isValidPlate(text string) (bool, string)`\r\nValidates if text matches Brazilian license plate patterns.\r\n\r\n## Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\r\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\r\n4. Push to the branch (`git push origin feature/amazing-feature`)\r\n5. Open a Pull Request\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## Acknowledgments\r\n\r\n- [GoCV](https://gocv.io/) - Go bindings for OpenCV\r\n- [gosseract](https://github.com/otiai10/gosseract) - Go bindings for Tesseract\r\n- [OpenCV](https://opencv.org/) - Computer vision library\r\n- [Tesseract OCR](https://github.com/tesseract-ocr/tesseract) - OCR engine\r\n\r\n## Future Implementations\r\n\r\nThe following features are planned for future releases:\r\n\r\n### 🔗 IP Camera Support\r\n- **RTSP Stream Integration**: Connect to IP cameras using RTSP protocol\r\n- **Multiple Camera Sources**: Support for multiple camera feeds simultaneously\r\n- **Network Camera Discovery**: Automatic detection of cameras on the network\r\n- **Camera Authentication**: Support for username/password protected cameras\r\n- **Stream Quality Control**: Adaptive streaming based on network conditions\r\n\r\n### 🚀 Webhook Integration\r\n- **Real-time Notifications**: Send HTTP webhooks when authorized plates are detected\r\n- **Configurable Endpoints**: Support for multiple webhook URLs\r\n- **Event Payload**: Rich JSON payload with plate information, timestamp, and confidence\r\n- **Retry Mechanism**: Automatic retry for failed webhook deliveries\r\n- **Authentication Support**: Bearer token and API key authentication for webhooks\r\n\r\n#### Example Webhook Payload:\r\n```json\r\n{\r\n  \"event\": \"plate_authorized\",\r\n  \"timestamp\": \"2025-06-03T14:30:00Z\",\r\n  \"plate\": {\r\n    \"number\": \"QFQ4H64\",\r\n    \"confidence\": 85.3,\r\n    \"format\": \"Old Brazilian format\"\r\n  },\r\n  \"camera\": {\r\n    \"id\": \"cam_001\",\r\n    \"location\": \"Main Entrance\"\r\n  },\r\n  \"access_granted\": true\r\n}\r\n```\r\n\r\n### 📊 Additional Planned Features\r\n- **Database Integration**: Store detection history and analytics\r\n- **REST API**: HTTP API for external system integration\r\n- **Mobile App**: Remote monitoring and configuration\r\n- **Cloud Storage**: Automatic image backup of detected plates\r\n- **Machine Learning**: Improved accuracy with custom trained models\r\n- **Multi-language Support**: OCR support for different countries' plates\r\n\r\n### 🛠️ Configuration Examples\r\n\r\n#### IP Camera Configuration (Planned)\r\n```go\r\n// Future IP camera configuration\r\ncameras := []CameraConfig{\r\n    {\r\n        ID: \"cam_001\",\r\n        URL: \"rtsp://admin:password@192.168.1.100:554/stream1\",\r\n        Location: \"Main Entrance\",\r\n        Active: true,\r\n    },\r\n    {\r\n        ID: \"cam_002\", \r\n        URL: \"rtsp://user:pass@192.168.1.101:554/live\",\r\n        Location: \"Parking Lot\",\r\n        Active: true,\r\n    },\r\n}\r\n```\r\n\r\n#### Webhook Configuration (Planned)\r\n```go\r\n// Future webhook configuration\r\nwebhooks := []WebhookConfig{\r\n    {\r\n        URL: \"https://api.company.com/access-control/webhook\",\r\n        Events: []string{\"plate_authorized\", \"plate_denied\"},\r\n        Headers: map[string]string{\r\n            \"Authorization\": \"Bearer your-token-here\",\r\n            \"Content-Type\": \"application/json\",\r\n        },\r\n        RetryAttempts: 3,\r\n        Timeout: 5000, // milliseconds\r\n    },\r\n}\r\n```\r\n\r\n**Contribution Welcome**: If you're interested in implementing any of these features, please check our [contributing guidelines](#contributing) and open an issue to discuss the implementation approach.\r\n\r\n## 📄License\r\n\r\nMIT License © [Raykavin Meireles](https://github.com/raykavin)\r\n\r\nPlaterecon is licensed under the MIT License. See the [LICENSE](LICENSE.md) file for details.\r\n\r\n---\r\n## 📬 Contact\r\n\r\nFeel free to reach out for support or collaboration:  \r\n**Email**: [raykavin.meireles@gmail.com](mailto:raykavin.meireles@gmail.com)  \r\n**GitHub**: [@raykavin](https://github.com/raykavin)\\\r\n**LinkedIn**: [@raykavin.dev](https://www.linkedin.com/in/raykavin-dev)\\\r\n**Instagram**: [@raykavin.dev](https://www.instagram.com/raykavin.dev)\r\n\r\n\r\n---\r\n\r\n**Note**: This system is designed for Brazilian license plates. For other countries, modify the regex patterns and validation logic accordingly.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraykavin%2Fplaterecon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraykavin%2Fplaterecon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraykavin%2Fplaterecon/lists"}